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, or flow.updated events?
  • 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.

EventTriggered WhenId fields
payment_intent.updatedA payment intent was updatedpayment_intent_id
payment_method.updatedA payment method was updatedpayment_method_id
flow.updatedA flow was updatedflow_id
dispute.updatedA dispute was updateddispute_id
payout_request.updatedA payout request changed statuspayout_request_id
organization.updatedAn organization was updatedorganization_id
app.updatedAn app was updatedapp_id
transfer.updatedA transfer was updatedtransfer_id
payout_link.updatedA payout link was updatedpayout_link_id
user.updatedA user was updateduser_id
user.onboardedA verification debit settled, verifying a bank account (once per verified account)user_id, ach_account_id, flow_id, transfer_id
user.onboarding_revokedA verification debit failed or was returned, leaving a bank account unverifieduser_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


Repository

hookdeck/webhook-skills

v0.1.0 · MIT · Updated Nov 16, 2026

View on GitHub →