Webhooks

Webhooks let your systems react to events in Sotto in real time. You subscribe to a topic by registering a callback address; when a matching event occurs, Sotto sends an HTTP POST to that address. Manage subscriptions with the Webhooks endpoints (create, list, retrieve, and update).

Topics

You can subscribe to the following topics:

Topic	Triggered when…	Payload
`user/opt-in`	A user opts in to messaging.	User object
`user/opt-out`	A user opts out of messaging.	User object
`user/update`	A user’s information is updated.	User object
`ticket/updated`	A support ticket is updated.	Ticket object

A brand may register multiple webhooks, and the same address may subscribe to the same topic more than once. In non-development environments, callback addresses must use HTTPS.

Callback requests

Sotto delivers events as a POST to your registered address. Callbacks are signed with the same HMAC scheme as API requests (see Authentication) and include these additional headers:

string

The API version for the callback (e.g. v1).

string

The UUID of the webhook subscription that triggered this callback.

string

The topic of the event (e.g. user/opt-in).

Payload

The body contains the time the event occurred and the associated resource:

{
  "date_occurred": "2024-03-18T19:39:27Z",
  "data": {
    "id": 1,
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Doe",
    "email_address": "jane.doe@example.com",
    "messaging_consent": true,
    "date_created": "2024-03-04T23:02:32Z",
    "date_last_updated": "2024-10-04T23:02:32Z",
    "location": {
      "city": "New York",
      "county": "New York",
      "postal_code": "10001",
      "state": "New York",
      "state_code": "NY"
    },
    "custom_data": {
      "loyalty_tier": "Gold",
      "loyalty_points": 1000
    }
  }
}

For user/* topics, data is a User object.

Responding

Your endpoint must return a 2xx status code within 10 seconds. Any other response — or a timeout — is treated as a failure and the callback is retried up to 20 times before being dropped.

Best practices

Make handlers idempotent

Retries mean your endpoint may receive the same event more than once. Use x-bigco-webhook-id together with date_occurred to detect and safely ignore duplicates.

Verify every signature

Always validate the HMAC signature on incoming callbacks before acting on them, and serve your endpoint over HTTPS.

Acknowledge fast, process async

Queue the event and return 200 immediately rather than doing heavy work inline. This keeps you within the 10-second window and avoids unnecessary retries.

Get started

Bulk data

Reference

Webhooks

Topics

Callback requests

Payload

Responding

Best practices

​Topics

​Callback requests

​Payload

​Responding

​Best practices

Topics

Callback requests

Payload

Responding

Best practices