# Guide to Dots Webhooks: Features and Best Practices

[Dots](https://usedots.com) is a payouts API. Platforms use it to pay creators, contractors and sellers through payout links and flows, move money between users with transfers, and onboard and verify the people receiving funds. Dots' webhooks tell your backend when any of those objects changes, but they deliberately say very little about the change: each one names the event and the ID of the resource, and you fetch the rest.

In this guide: Dots' 12 events and their ID-only payloads, adding endpoints through the Svix dashboard that Dots links to, verifying Svix signatures, and the delivery details that Dots leaves to Svix.

## What are Dots webhooks?

Dots delivers webhooks through Svix. You don't register endpoints on a Dots screen; the **API Management** tab of an app or organisation in the Dots dashboard links you to a Svix dashboard where you add them. Endpoints at the organisation level also receive events that originate in its apps, with an extra `api_app_id` field telling you which app.

The payloads are flat. `event` holds the event name and sits beside the ID of the resource that changed, such as `flow_id` or `transfer_id`. Dots recommends subscribing to the canonical `.updated` events and fetching the resource by ID to read its current state, which also sidesteps problems with stale or out-of-order events.

Dots' own page doesn't print the header names or the secret format; it links to Svix's verification guide. The `svix-*` header names and `whsec_` secrets below are Svix's defaults, and Hookdeck's Dots source is configured the same way.

## Dots webhook features

| Feature | Details |
| --- | --- |
| Configuration | Svix dashboard, via **API Management** in the Dots dashboard |
| Scope | Per app, or organisation-level (includes app events, tagged `api_app_id`) |
| Subscription model | Selected event types. None selected means all events |
| Rate limit | Optional, per endpoint |
| Delivery platform | Svix |
| Headers | `svix-id`, `svix-timestamp`, `svix-signature` (Svix defaults) |
| Signature | Standard Webhooks HMAC-SHA256, `v1,<base64>` |
| Secret | One per endpoint (Svix secrets start with `whsec_`) |
| Body | `event` plus resource ID fields |
| Event routing | Body field `event` |
| Response window | `2xx` within 15 seconds |
| Retries | Not documented by Dots |
| Source IPs | Not published |

## Events and payloads

| Documented event | Meaning |
| --- | --- |
| `payment_intent.updated` | A payment intent object was updated. |
| `payment_method.updated` | A payment method object was updated. |
| `flow.updated` | A flow was updated. |
| `dispute.updated` | A dispute was updated. |
| `payout_request.updated` | A payout request changed status. |
| `organization.updated` | An organization object was updated. |
| `app.updated` | An app object was updated. |
| `transfer.updated` | A transfer was updated. |
| `payout_link.updated` | A payout link was updated. |
| `user.updated` | A user was updated. |
| `user.onboarded` | A verification debit settled, verifying the bank account it drew from (`ach_account_id`). |
| `user.onboarding_revoked` | A verification debit failed or was returned, leaving the bank account it drew from (`ach_account_id`) unverified. |

A delivery for a flow looks like this, with the placeholder ID Dots' catalogue uses:

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

```

Other events carry their own ID fields, such as `payment_intent_id`, `transfer_id`, `user_id` or `ach_account_id`. `user.onboarding_revoked` also includes a `reason`. None of the bodies includes the resource's status or amounts, so a handler that needs them calls the Dots API.

## Setting up Dots webhooks

1. In the Dots dashboard, pick an app from the sidebar, or open the organisation settings for organisation-level webhooks.
2. Open **API Management** and follow the link to the Svix dashboard.
3. Click **+ Add Endpoint**, enter your URL (for example `https://example.com/webhooks/dots`) and an optional description.
4. Choose event types. If you choose none, the endpoint gets every event.
5. Set a rate limit if your receiver needs one, then click **Create**.
6. Copy the endpoint's signing secret and store it as `DOTS_WEBHOOK_SECRET`. It belongs to this endpoint only.

Check that the secret starts with `whsec_`. Dots doesn't document the format, and the verifier in this guide and Hookdeck's Dots source both expect it. To receive events on your laptop, start a tunnel with the [Hookdeck CLI](/docs/cli) and use its URL as the endpoint:

```bash
npx hookdeck-cli listen 3000 dots --path /webhooks/dots

```

**With Hookdeck.** Add a Hookdeck source with the **Dots** type, paste the endpoint's secret, and use the source URL as the Svix endpoint. The source accepts only `POST`. Every request gets a `200` from Hookdeck, and those with signatures that don't match are labelled failed verification and kept away from your destination.

## Securing Dots webhooks

Svix signs `{svix-id}.{svix-timestamp}.{raw body}` with HMAC-SHA256, keyed with the base64-decoded secret after `whsec_`, and sends one or more `v1,<base64>` entries in `svix-signature`. Because Dots doesn't name the headers itself, the function below reads `svix-*` and falls back to `webhook-*` in case they are ever white-labelled. Use a matching set of three, never a mix.

```javascript
const crypto = require('node:crypto');

function decodeBase64(value) {
  if (typeof value !== 'string' || !/^[A-Za-z0-9+/]+={0,2}$/.test(value)) return null;
  const bytes = Buffer.from(value, 'base64');
  return bytes.length > 0 && bytes.toString('base64').replace(/=+$/, '') === value.replace(/=+$/, '')
    ? bytes : null;
}

function verifySignature(rawBody, headers, secret) {
  if (!Buffer.isBuffer(rawBody) || typeof secret !== 'string' || !secret) return false;
  const prefix = headers['svix-id'] ? 'svix' : 'webhook';
  const id = headers[`${prefix}-id`];
  const timestamp = headers[`${prefix}-timestamp`];
  const signature = headers[`${prefix}-signature`];
  if (typeof id !== 'string' || !id || typeof timestamp !== 'string' ||
      !/^[0-9]+$/.test(timestamp) || typeof signature !== 'string') return false;
  const key = decodeBase64(secret.replace(/^whsec_/, ''));
  if (!key) return false;
  const message = Buffer.concat([Buffer.from(`${id}.${timestamp}.`, 'utf8'), rawBody]);
  const candidates = signature.split(/\s+/).filter((item) => item.startsWith('v1,')).map((item) => item.slice(3));
  const expected = crypto.createHmac('sha256', key).update(message).digest();
  return candidates.some((candidate) => {
    const received = decodeBase64(candidate);
    if (!received) return false;
    return received.length === expected.length && crypto.timingSafeEqual(received, expected);
  });
}

```

The handler only needs the event name and ID, then hands off a fetch of the current state:

```javascript
const express = require('express');

// Returns the parsed body when it is a JSON object, otherwise null.
function parseJsonObject(rawBody) {
  try {
    const value = JSON.parse(rawBody.toString('utf8'));
    return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
  } catch {
    return null;
  }
}

const app = express();

const ID_FIELDS = ['transfer_id', 'flow_id', 'payout_link_id', 'payout_request_id', 'user_id', 'payment_intent_id'];

app.post('/webhooks/dots', express.raw({ type: '*/*' }), async (req, res) => {
  const secret = process.env.DOTS_WEBHOOK_SECRET;
  if (!secret) return res.sendStatus(500);
  if (!verifySignature(req.body, req.headers, secret)) return res.sendStatus(401);

  const payload = parseJsonObject(req.body);
  if (!payload) return res.sendStatus(400); // signed, but not a JSON object
  if (typeof payload.event !== 'string') return res.sendStatus(400);
  const idField = ID_FIELDS.find((field) => payload[field]);
  try {
    await refreshQueue.add({
      messageId: req.headers['svix-id'] || req.headers['webhook-id'],
      event: payload.event,
      resourceId: idField ? payload[idField] : null,
      appId: payload.api_app_id, // set on app events sent to an organisation endpoint
    });
  } catch {
    return res.sendStatus(503); // not processed, so don't acknowledge
  }
  return res.sendStatus(200);
});

```

`refreshQueue` is a stand-in for your own queue; the worker behind it calls the Dots API for the resource. The ID field names come from Dots' event catalogue.

Dots asks you to check the timestamp as well as the signature, and the Svix library does that with a 5-minute window. Hookdeck applies no window and passes the original `svix-timestamp` through on retries and replays. If your endpoint sits behind Hookdeck, verify the signature only, and let deduplication on `svix-id` and fetching fresh state protect you from replays.

> **Make Dots webhooks production-ready.** [Hookdeck Event Gateway](/event-gateway) verifies Dots' Svix signatures, holds every transfer and payout event, and can pace the API lookups your workers make.

## Dots webhook limitations and pain points

### The scheme is documented by Svix, not Dots

**The Problem:** You're not sure which headers to read or what the secret looks like.

**Why It Happens:** Dots' webhook page says it uses Svix and links Svix's instructions, but doesn't name the headers or show the secret.

**Workarounds:**

* Inspect one real delivery to confirm the header names before you deploy.
* Read both `svix-*` and `webhook-*` names, as the verifier above does.

**How Hookdeck Can Help:** Hookdeck shows the exact headers and body of every request that reaches a source, and its Dots source accepts either header set.

### No retry policy stated

**The Problem:** You don't know how long Dots will keep trying after your endpoint fails.

**Why It Happens:** Dots gives a 15-second response window but no retry schedule or disabling policy. Svix's defaults probably apply, but Dots doesn't say so.

**Workarounds:**

* Respond within 15 seconds and do the API lookup afterwards.
* After an outage, re-fetch recent transfers and payout requests from the API.

**How Hookdeck Can Help:** Hookdeck takes delivery immediately and [retries](/docs/retries) to your service under a policy you control.

### Every event costs an API call

**The Problem:** A burst of `.updated` events turns into a burst of API requests from your workers.

**Why It Happens:** Payloads carry only IDs, by design.

**Workarounds:**

* Collapse repeated events for the same resource ID before fetching.
* Use the endpoint's rate limit to smooth bursts.

**How Hookdeck Can Help:** A [maximum delivery rate](/docs/destinations) on the Hookdeck destination limits how fast events, and the lookups behind them, reach your workers.

### Example payloads use placeholder IDs

**The Problem:** You can't build test fixtures from the docs.

**Why It Happens:** Dots' catalogue uses values like `"flow_id": "flow-id"`.

**Workarounds:**

* Trigger events in a test app and record the real bodies.

**How Hookdeck Can Help:** Requests that reach a Hookdeck source are kept with their headers, so real deliveries become fixtures you can replay.

## Best practices

### Fetch state, don't trust order

The body tells you something changed, not what it changed to. Fetch the resource and apply what the API returns; that is correct whatever order events arrive in.

### Deduplicate on `svix-id`

Svix keeps the same ID when it resends a message. Store it before you enqueue work. Patterns for this are in our [guide to webhook idempotency](/webhooks/guides/implement-webhook-idempotency).

### Watch `user.onboarding_revoked`

A failed or returned verification debit leaves the user's bank account unverified. Pause payouts to that account and show the `reason` to whoever handles onboarding.

### Keep the raw body and skip CSRF

Use `express.raw({ type: '*/*' })`, `await request.text()` in a Next.js route handler, or `await request.body()` in FastAPI, and switch off CSRF protection on the webhook route, as Dots advises.

## Conclusion

Dots keeps its webhooks minimal: an event name and an ID, delivered and signed by Svix. Verify with the endpoint's Svix secret, answer within 15 seconds, deduplicate on `svix-id`, and fetch the transfer, flow or user to see what actually changed. Confirm the header names on a real delivery, since Dots leaves them to Svix's defaults.

[Hookdeck Event Gateway](https://hookdeck.com) can receive those events for you, check the signature and feed them to your workers at a steady rate. [Sign up for free](https://dashboard.hookdeck.com/signup) to add a Dots source.