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

When creating an endpoint on Svix, you can subscribe to a wide list of events to receive notifications. The following accordions list the available events and present webhook notifications examples:

app.updated

Triggered when an App object is updated.

{
"app_id": "5d9278aa-ddac-4df6-9063-696d32b3baf9"
}

flow.transaction_updated

Triggered when ACH transaction details within a flow are updated.

  {
  "event": "flow.transaction_updated",
  "flow_id": "d48d42ca-efdf-4b41-b3a7-aa3cdd6c129f"
  }

flow.updated

Called when a flow has been updated due to a user completing steps.

{
"event": "flow.updated",
"flow_id": "d48d42ca-efdf-4b41-b3a7-aa3cdd6c129f"
}

payment_intent.updated

Triggered when a payment intent object is updated.

{
"payment_intent_id": "0feee270-d3c9-434a-b432-eb6f4ff4a234"
}

payout_link.claimed

Occurs when a payout link is claimed by a user.

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "created": "2023-11-07T05:31:56Z",
  "link": "<string>",
  "amount": 123,
  "status": "created",
  "payee": {
    "first_name": "<string>",
    "last_name": "<string>",
    "email": "[e-mail]",
    "country_code": "<string>",
    "phone_number": "<string>"
  },
  "delivery": {
    "method": "link",
    "email": "[e-mail]",
    "country_code": "<string>",
    "phone_number": "<string>"
  },
  "tax_exempt": true,
  "claimed_user_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "flow_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "metadata": "<string>"
}

payout_link.paid_out

Occurs when a user completes a payout through a payout link, either in full or partially.

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "created": "2023-11-07T05:31:56Z",
  "link": "<string>",
  "amount": 123,
  "status": "created",
  "payee": {
    "first_name": "<string>",
    "last_name": "<string>",
    "email": "[e-mail]",
    "country_code": "<string>",
    "phone_number": "<string>"
  },
  "delivery": {
    "method": "link",
    "email": "[e-mail]",
    "country_code": "<string>",
    "phone_number": "<string>"
  },
  "tax_exempt": true,
  "claimed_user_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "flow_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "metadata": "<string>"
}

payout_link.sent

Occurs when a payout link is sent out, whether via email, SMS, or direct link.

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "created": "2023-11-07T05:31:56Z",
  "link": "<string>",
  "amount": 123,
  "status": "created",
  "payee": {
    "first_name": "<string>",
    "last_name": "<string>",
    "email": "[e-mail]",
    "country_code": "<string>",
    "phone_number": "<string>"
  },
  "delivery": {
    "method": "link",
    "email": "[e-mail]",
    "country_code": "<string>",
    "phone_number": "<string>"
  },
  "tax_exempt": true,
  "claimed_user_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "flow_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "metadata": "<string>"
}

payout_link.updated

Triggered when there is a change in the status of a payout link.

{
"event": "payout_link.updated",
"payout_link_id": "1324f3e4-aa5d-45f0-8128-a77a57c51cb3"
}

payout_request.updated

Occurs when a payout request changes status.

refund.updated

Triggered when a refund object is updated.

{
"refund_id": "169a5d87-041b-4d49-ba9d-2e45f8fe9183"
}

transfer.completed

Triggered when a transfer is completed. This is a terminal state. The complete transfer object will be included in the payload.

{
"transfer": {
  "amount": 123,
  "created": "2023-11-07T05:31:56Z",
  "external_data": {
  "account_id": "<string>",
  "external_id": "<string>",
  "platform": "ach"
  },
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "metadata": "<string>",
  "status": "completed",
  "transactions": [
  {
    "amount": 123,
    "created": "2023-11-07T05:31:56Z",
    "destination_name": "<string>",
    "id": 123,
    "metadata": "<string>",
    "source_name": "<string>",
    "type": "balance"
  }
  ],
  "type": "refill",
  "user_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
},
"transfer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}

transfer.failed

Triggered when a transfer fails. This is a terminal state. The complete transfer object will be included in the payload.

{
"transfer": {
  "amount": 123,
  "created": "2023-11-07T05:31:56Z",
  "external_data": {
  "account_id": "<string>",
  "external_id": "<string>",
  "platform": "ach"
  },
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "metadata": "<string>",
  "status": "failed",
  "transactions": [
  {
    "amount": 123,
    "created": "2023-11-07T05:31:56Z",
    "destination_name": "<string>",
    "id": 123,
    "metadata": "<string>",
    "source_name": "<string>",
    "type": "balance"
  }
  ],
  "type": "refill",
  "user_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
},
"transfer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}

transfer.updated

When there is a change to a transfer status.

{
  "event": "transfer.updated",
  "transfer_id": "68db1237-3953-47b0-86aa-739a201dcb16"
}

user.updated.background_check

Triggered when a user’s background check is completed.

{
  "user_id": "some string"
}

user.updated.ide_verified

Triggered when a user’s ID is verified.

{
  "user_id": "some string"
}

user.updated.payout_method

Triggered when a user’s payout method is updated.

  {
    "user_id": "some string"
  }

Webhook Signing

Find the instructions to verify webhooks here