Agent skill
Dots Webhooks Skill
Receive and verify Dots webhooks (payouts API, delivered via Svix). Use when setting up Dots webhook handlers, debugging svix-signature verification, or handling events like transfer.updated, payout_link.updated, flow.updated, and user.onboarded.
Install this skill
npx skills add hookdeck/webhook-skills --skill dots-webhooks
Dots (usedots.com), a payouts API for payout links, flows, transfers, and user onboarding, delivers webhooks through Svix. Every delivery is an HTTP POST with a JSON body and three signature headers: svix-id, svix-timestamp, and svix-signature. The event name is the top-level event field. Payloads carry only the changed resource's id (for example transfer_id), so fetch the resource from the Dots API for its current state.
When to Use This Skill
- How do I receive Dots webhooks?
- How do I verify Dots webhook signatures (
svix-signature)? - How do I handle
transfer.updated,payout_link.updated, orflow.updatedevents? - How do I know when a user is onboarded (
user.onboarded) or revoked (user.onboarding_revoked)? - Why is my Dots webhook signature verification failing, or rejecting Hookdeck retries?
Verification (core)
Signed content is {svix-id}.{svix-timestamp}.{raw body}. Svix signs it with HMAC-SHA256 using the base64-decoded secret (the part after whsec_), base64-encodes the result, and sends one or more space-delimited v1,<signature> entries. Dots points to Svix's verification guide; the official svix library compares signatures in constant time.
import { Webhook } from 'svix'; // svix 2.x is ESM-only
// svix-* headers, or the Standard Webhooks webhook-* names when svix-id is absent
const prefix = req.headers['svix-id'] ? 'svix' : 'webhook';
const id = req.headers[`${prefix}-id`];
const timestamp = req.headers[`${prefix}-timestamp`];
const signature = req.headers[`${prefix}-signature`];
const wh = new Webhook(process.env.DOTS_WEBHOOK_SECRET); // "whsec_..."
// rawBody: the raw Buffer/string, never re-serialized JSON
wh.verify(rawBody, {
'svix-id': id, 'svix-timestamp': timestamp, 'svix-signature': signature,
'webhook-id': id, 'webhook-timestamp': timestamp, 'webhook-signature': signature,
}); // throws on a bad signature or a timestamp outside the window
const event = JSON.parse(rawBody.toString('utf8')); // parse only after verify passes
from svix.webhooks import Webhook, WebhookVerificationError
wh = Webhook(os.environ["DOTS_WEBHOOK_SECRET"])
wh.verify(raw_body, {"svix-id": id, "svix-timestamp": ts, "svix-signature": sig,
"webhook-id": id, "webhook-timestamp": ts, "webhook-signature": sig})
For complete handlers with tests, see examples/express/, examples/nextjs/, examples/fastapi/.
Header names. Dots' docs don't name the headers; svix-* is the Svix default, and Svix also sends the same values as Standard Webhooks webhook-id, webhook-timestamp, and webhook-signature. The examples read svix-* and fall back to webhook-* when svix-id is absent. Never mix the two sets within one request.
Secret format. One signing secret per endpoint, shown in the Svix dashboard when you create the endpoint. Dots' docs don't print it; Svix secrets start with whsec_, and the examples reject a secret without that prefix (a 500, so verification fails closed). Store the full whsec_... value in DOTS_WEBHOOK_SECRET.
Hookdeck retries and replays hit the 5-minute window
The svix and standardwebhooks libraries always enforce a fixed 5-minute timestamp window, and it can't be configured. Hookdeck retries and replays resend the original svix-timestamp, so the library rejects any retry or replay that happens more than 5 minutes after the original delivery. If you verify behind Hookdeck (or replay old events), use the manual verifier in references/verification.md, where the window can be dropped or widened. Deduplicate on svix-id instead of relying on the timestamp.
Common Event Types
The event name is the top-level event field. Dots recommends subscribing to the canonical .updated events and fetching the resource by the id in the payload. The list below is the 12 events Dots documents and may not be exhaustive.
| Event | Triggered When | Id fields |
|---|---|---|
payment_intent.updated | A payment intent was updated | payment_intent_id |
payment_method.updated | A payment method was updated | payment_method_id |
flow.updated | A flow was updated | flow_id |
dispute.updated | A dispute was updated | dispute_id |
payout_request.updated | A payout request changed status | payout_request_id |
organization.updated | An organization was updated | organization_id |
app.updated | An app was updated | app_id |
transfer.updated | A transfer was updated | transfer_id |
payout_link.updated | A payout link was updated | payout_link_id |
user.updated | A user was updated | user_id |
user.onboarded | A verification debit settled, verifying a bank account (once per verified account) | user_id, ach_account_id, flow_id, transfer_id |
user.onboarding_revoked | A verification debit failed or was returned, leaving a bank account unverified | user_id, ach_account_id, flow_id, transfer_id, reason |
App-originated webhooks sent to an organization-level endpoint also carry api_app_id. See references/overview.md for payloads.
Environment Variables
# Signing secret of the webhook endpoint (Svix format, starts with whsec_)
DOTS_WEBHOOK_SECRET=whsec_xxxxx
Local Development
# Start tunnel (no account needed)
npx hookdeck-cli listen 3000 dots --path /webhooks/dots
Register the tunnel URL as an endpoint in the Svix dashboard linked from the Dots dashboard (API Management tab), then trigger a flow or transfer to receive events.
Reference Materials
- references/overview.md - Dots webhook concepts, events, payloads
- references/setup.md - Add an endpoint in the Svix dashboard and get the signing secret
- references/verification.md - Svix verification details, manual verifier, timestamp window