Webhooks

Webhooks in Brightsy AI allow external systems to trigger scenarios or receive notifications when events occur. This guide will walk you through the process of managing webhooks for integrating Brightsy with your external applications and services.

Table of Contents

1. Accessing Webhooks
2. Creating a New Webhook
3. Editing an Existing Webhook
4. Testing a Webhook
5. Deleting a Webhook
6. Understanding Webhook Fields
7. Using Webhooks with Scenarios
8. Troubleshooting

1. Accessing Webhooks

To manage webhooks, navigate to the "Webhooks" section under Utilities in your account dashboard. Here, you will see a list of all existing webhooks associated with your account.

Webhook Properties

2. Creating a New Webhook

1. Navigate to Webhooks: Go to the "Webhooks" section from Utilities in your account dashboard.
2. Click "Create New Webhook": This button is located at the top right of the webhooks list.
3. Fill in the Webhook Details: Enter the name and optional description for your webhook.
4. Select a Scenario: Choose the scenario that should be triggered when the webhook receives a request.
5. Set the Status: Choose whether the webhook should be active immediately.
6. Save the Webhook: Click the "Save" button to create the webhook.
7. Copy the Webhook URL: After creation, copy the generated webhook URL to use in your external systems.

3. Editing an Existing Webhook

1. Select a Webhook: Click on the webhook you wish to edit from the list.
2. Modify the Details: Update any fields as necessary, such as changing the name, description, scenario, or status.
3. Save Changes: Click the "Save" button to apply your changes.

4. Testing a Webhook

1. Select a Webhook: Choose the webhook you want to test.
2. Click "Test Webhook": Use the test button to send a sample payload.
3. Review the Response: Check the response to ensure the webhook is configured correctly.
4. Check Scenario Execution: Verify that the linked scenario was triggered successfully.

5. Deleting a Webhook

1. Select a Webhook: Choose the webhook you want to delete.
2. Access the Danger Zone: Scroll to the bottom of the webhook details page.
3. Delete the Webhook: Click the "Delete" button in the Danger Zone section. Confirm the deletion when prompted.

6. Understanding Webhook Fields

• Name: A descriptive identifier for your webhook.
• Description: A brief explanation of the webhook's purpose and what triggers it.
• Status: Indicates whether the webhook is active (receiving requests) or inactive.
• Scenario: The scenario that will be executed when the webhook receives a valid request.
• Secret: A secure key used to verify that incoming requests are authentic. Include this in your request headers.
• URL: The unique endpoint URL that external systems should send requests to.

7. Using Webhooks with Scenarios

Sending a Request to Your Webhook

To trigger a webhook, send an HTTP POST request to your webhook URL:

curl -X POST https://app.brightsy.ai/api/webhooks/{webhook-id} \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Secret: your-webhook-secret" \
  -d '{"key": "value", "data": "your payload"}'

Request Headers

Request Body

The request body should be a valid JSON object. This data will be passed to the linked scenario as input.

Response Codes

8. Troubleshooting

Webhook Not Triggering

• Verify that the webhook status is set to "Active"
• Check that the correct scenario is linked
• Ensure the X-Webhook-Secret header matches your webhook's secret

Authentication Errors

• Double-check that you're using the correct webhook secret
• Ensure the secret is included in the X-Webhook-Secret header

Scenario Not Executing

• Verify the linked scenario is enabled
• Check that the scenario's agent is properly configured
• Review the scenario's instruction to ensure it can handle the webhook payload

Invalid Payload Errors

• Ensure your request body is valid JSON
• Check that required fields expected by the scenario are included

For further assistance, please contact Brightsy AI support or refer to the in-app help resources.