Gareth Wilson Gareth Wilson

Guide to Dots Webhooks: Features and Best Practices

Published


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

FeatureDetails
ConfigurationSvix dashboard, via API Management in the Dots dashboard
ScopePer app, or organisation-level (includes app events, tagged api_app_id)
Subscription modelSelected event types. None selected means all events
Rate limitOptional, per endpoint
Delivery platformSvix
Headerssvix-id, svix-timestamp, svix-signature (Svix defaults)
SignatureStandard Webhooks HMAC-SHA256, v1,<base64>
SecretOne per endpoint (Svix secrets start with whsec_)
Bodyevent plus resource ID fields
Event routingBody field event
Response window2xx within 15 seconds
RetriesNot documented by Dots
Source IPsNot published

Events and payloads

Documented eventMeaning
payment_intent.updatedA payment intent object was updated.
payment_method.updatedA payment method object was updated.
flow.updatedA flow was updated.
dispute.updatedA dispute was updated.
payout_request.updatedA payout request changed status.
organization.updatedAn organization object was updated.
app.updatedAn app object was updated.
transfer.updatedA transfer was updated.
payout_link.updatedA payout link was updated.
user.updatedA user was updated.
user.onboardedA verification debit settled, verifying the bank account it drew from (ach_account_id).
user.onboarding_revokedA 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

  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 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-* 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 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.


Gareth Wilson

Gareth Wilson

Product Marketing

Multi-time founding marketer, Gareth is PMM at Hookdeck and author of the newsletter, Community Inc.