Guide to Dots Webhooks: Features and Best Practices
Dots 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:
{
"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
- In the Dots dashboard, pick an app from the sidebar, or open the organisation settings for organisation-level webhooks.
- Open API Management and follow the link to the Svix dashboard.
- Click + Add Endpoint, enter your URL (for example
https://example.com/webhooks/dots) and an optional description. - Choose event types. If you choose none, the endpoint gets every event.
- Set a rate limit if your receiver needs one, then click Create.
- 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 and use its URL as the endpoint:
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.
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:
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 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-*andwebhook-*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 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 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.
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 can receive those events for you, check the signature and feed them to your workers at a steady rate. Sign up for free to add a Dots source.