Order Webhooks

What webhooks do

A webhook is a way for DabDash to tell your own systems — your CRM, your automation tool, your custom server — the moment something happens in your store. When a customer places a new order, DabDash sends a short HTTPS request to a URL you supply. Your system reads the order and does whatever you want with it: drop it into a CRM pipeline, send a payment link, kick off a delivery dispatch, notify a Slack channel.

Today DabDash sends one event — order.created — the instant an order is placed. The order is in pending status at that point. Other status changes do not fire a webhook (yet).

Endpoint URL

This is the URL DabDash will POST each new order to. It must be:

• HTTPS only — http:// URLs are rejected.
• Publicly reachable — we block private IP ranges (anything on 10.x, 172.16-31.x, 192.168.x, 127.x, link-local). Your CRM must be on the public internet.
• Stable — if your URL changes, update it here. We do not retry failed deliveries beyond 4 attempts.

Active toggle

Flip this off to pause delivery without losing your configuration. When the toggle is off, no events are sent. The same toggle is mirrored on the Webhook payment method card under Settings › Payment Methods — turning one off turns the other off too.

The signing secret

Every request DabDash sends to your endpoint includes a header called X-DabDash-Signature. This header contains an HMAC-SHA256 of the entire request body, computed using your secret. Your server should:

1. Read the raw request body before parsing JSON.
2. Compute sha256=HMAC-SHA256(body, secret).
3. Compare the computed value against the X-DabDash-Signature header using a constant-time comparison.
4. Reject the request if the values do not match — that means somebody other than DabDash sent it.

You can rotate the secret at any time. The old secret stops working immediately — not after a delay — so make sure your server is using the new value before you press the rotate button.

Sending a test payload

Once you've saved a URL and your endpoint is live, click Test webhook to fire a synthetic order.created payload at your endpoint. The payload is signed with your current secret — great for confirming your signature-verification code is working before a real customer order arrives.

The synthetic payload's order_number is TEST-PING and the body includes "test": true so your downstream system can skip it.

Custom headers (Advanced)

Click Advanced to reveal the custom headers section. Some CRMs require extra headers to accept requests — for example, a Authorization: Bearer ... token, a tenant identifier like X-Shop-Id: 42, or a fixed API key. Add up to 20 name/value pairs; they ship with every webhook request.

A handful of header names are reserved and rejected: Host, Content-Type, Content-Length, and any header starting with X-DabDash- — DabDash controls those.

What's in the payload

The body is JSON. Top-level fields:

• event — always order.created right now.
• timestamp — Unix seconds, when the webhook was prepared.
• tenant — { id, slug, name }, identifying your shop.
• order — { id, order_number, status, payment_method, subtotal_cents, total_cents, currency, customer, items, created_at }.
• test — only present (true) for test pings.

Reliability & retries

DabDash retries failed deliveries with exponential backoff: 4 attempts total, with delays of 1 min, 5 min, and 15 min between them. We retry on 5xx server errors and connection failures, but not on 4xx responses — a 4xx means your endpoint accepted the request but rejected it as bad input, which is a configuration problem, not a transient failure.

After the final failure, the order continues normally — webhook delivery does not block checkout. The failure shows up on the order detail page under Payment activity as "CRM notification failed".