Configure your webhooks

Introduction

Webhooks are a way for us to notify your applications when specific events occur within the Bridge API system. This real-time communication method enables your application to stay updated and respond immediately to important events.

Create a webhook from the dashboard

You can create webhooks from your dashboard. We will ask you to define:

• your callback URL for this webhook
• an optional name
• the events you want to receive

You can create up to 10 webhooks per application.

To secure your webhooks, we recommend you to use the secret we provide when you create them. Please see the dedicated section to get the security best practices.

You can easily set up webhooks from your Bridge API dashboard. When creating a webhook, you will need to specify:

• Your callback URL: This is where we will send webhook payloads.
• An optional name for your webhook.
• The specific events you want to receive notifications for.

Each application can create up to 10 webhooks. To enhance the security of your webhooks, we strongly recommend utilizing the secret provided when creating them. Refer to the dedicated section for best practices on securing your webhooks.

Please note that only admins have the authority to manage webhooks.

Test your webhook with our test event

Once you've created a webhook, you can perform a test directly from your dashboard by clicking the "Send a test" button. This action triggers a simulated event, and your webhook will receive the following response:

{
  "content": {
    "item_id": 1234567890,
    "status": 0,
    "user_uuid": "9a95b38f-f98b-417a-988b-9d0d584893e7"
  },
  "timestamp": 1611681789,
  "type": "TEST_EVENT"
}

This enables you to ensure that your webhook is properly configured and able to receive and process events.

Retry mechanism

When we call your webhook, we expect your server to respond with a 200 status code indicating success. It's essential to provide this successful response as quickly as possible. If no response is received within a reasonable time, we will attempt to retry the event. To prevent potential issues, it's advisable to design your webhook handlers to run asynchronously and handle any long-running processes outside of the webhook endpoint.

In cases where we encounter an error while sending a message to your webhook, such as a non-2xx HTTP status code or a delayed response, we will initiate retries for 1 to 2 days. This includes a exponential back-off mechanism to ensure reliable webhook delivery.

🚧

Due to potential retries, you may receive webhooks for events related to deleted users or items. It's essential to handle such cases gracefully in your webhook processing logic.