Webhooks

Introduction

Webhooks are how services notify each other of events, so in Dots they let you receive real-time notifications for things like Payout Links, Flows, and Transfers. At their core they are just a POST request to a pre-determined endpoint that you can configure from the dashboard UI. You normally use one endpoint per service, and that endpoint listens to all event types. For example, if you receive webhooks from Acme Inc., you can structure your URL like https://www.example.com/acme/webhooks/.

The way to indicate that a webhook has been processed is by returning a 2xx (status code 200-299) response to the webhook message within a reasonable time-frame (15s). It’s also important to disable CSRF protection for this endpoint if the framework you use enables it by default.

Another important aspect of handling webhooks is to verify the signature and timestamp when processing them. You can learn more about it in the signature verification section.

Configuring Webhooks

Dots uses Svix to deliver webhooks. To access the Svix dashboard, follow the instructions below:

1. Access the Dots dashboard.
2. From the sidebar, choose the desired App from your list or head to the Organization settings to configure organization level webhooks.
3. Navigate to the API Management tab for the link to the Svix dashboard.

Once in the Svix dashboard do the following:

1. Click on + Add Endpoint to add a new webhook.
2. Provide a URL or use an endpoint generated by Svix. Optionally, add a description to define the purpose of the webhook.
3. Select the event types to which the endpoint should be subscribed. If no event is selected, the webhook will register for all events.
4. Optionally, enable a rate limit for the endpoint.
5. Click Create.
6. Note the webhook signing secret.

A new endpoint will be created to group all information from the notification received.

Available events

Subscribe to the canonical .updated event for each resource. When an event arrives, fetch the resource by the identifier in the payload to retrieve its current state.

Every payload includes an event field. App-originated webhooks sent to an organization-level endpoint also include the originating api_app_id.

{
  "event": "payment_intent.updated",
  "payment_intent_id": "payment-intent-id"
}

{
  "event": "payment_method.updated",
  "payment_method_id": "payment-method-id"
}

{
  "event": "flow.updated",
  "flow_id": "flow-id"
}

{
  "dispute_id": "dispute-id",
  "event": "dispute.updated"
}

{
  "event": "payout_request.updated",
  "payout_request_id": "payout-request-id"
}

{
  "event": "organization.updated",
  "organization_id": "organization-id"
}

{
  "app_id": "app-id",
  "event": "app.updated"
}

{
  "event": "transfer.updated",
  "transfer_id": "transfer-id"
}

{
  "event": "payout_link.updated",
  "payout_link_id": "payout-link-id"
}

{
  "event": "user.updated",
  "user_id": "user-id"
}

Webhook Signing

Find the instructions to verify webhooks here.