Skip to main content

Overview

Dancity sends an HTTP POST to your configured webhook URL whenever a transaction event occurs. You implement the receiving endpoint on your server; Dancity does not expose this as an API you call. This lets you keep your system in sync without polling the transactions endpoint.

Setting up your webhook URL

  1. Go to your API Key page
  2. Enter your webhook URL under Webhook URL — it must be HTTPS
  3. Click Save Webhook URL
Your webhook URL must be publicly accessible. Localhost URLs will not work in production. Use a tool like ngrok during local development.

Event payload

All webhook payloads share the same envelope structure:

Event types

Verifying webhook signatures

Every webhook request includes an X-Dancity-Signature header. You must verify this signature to confirm the request is genuinely from Dancity and has not been tampered with. The signature is computed as:
Your webhookSecret is shown when you first generate your API key. Store it securely — it is not shown again.

Verification examples

Always use a timing-safe comparison function (e.g. crypto.timingSafeEqual, hmac.compare_digest, hash_equals) to prevent timing attacks.

Retry policy

If your endpoint returns any HTTP status other than 2xx, Dancity will retry the delivery with exponential backoff: After 5 failed attempts, the event is marked as undeliverable.

Best practices

Return a 200 response as fast as possible — ideally within 5 seconds. Move any heavy processing (database writes, emails) to an async job/queue.
You may receive the same event more than once due to retries. Use transactionId or reference as a unique key to ensure you don’t process the same transaction twice.
Save the raw payload and the X-Dancity-Signature header for every incoming webhook. This makes debugging failed deliveries much easier.
Run ngrok http 3000 to get a public HTTPS URL that tunnels to your local server. Set that URL as your webhook URL during development.