Overview

Setting up your webhook URL

Configure your webhook URL in the Chowdeck Dashboard:

https://dashboard.chowdeck.com/settings/developers

All webhook events are sent as HTTP POST requests to this URL with a JSON body.

Payload structure

Every webhook event shares the same top-level structure:

{
  "category": "ORDER_CREATED",
  "description": "New order",
  "payload": { ... }
}

Verifying webhook signatures

All webhook requests include an x-chowdeck-signature header. You must verify this signature to confirm the request genuinely came from Chowdeck and has not been tampered with.

Verification steps:

1. Retrieve the x-chowdeck-signature header from the request
2. Compute an HMAC SHA-256 digest of the raw request body using your webhook secret
3. Compare the computed digest with the received signature
4. Reject the request if they do not match

Example (Node.js):

const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const computed = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(computed, 'utf8'),
    Buffer.from(signature, 'utf8')
  );
}

Always use crypto.timingSafeEqual for signature comparison. Standard string equality (===) is vulnerable to timing attacks.

Responding to webhooks

Your endpoint must return a 200 OK response as quickly as possible to acknowledge receipt. If your processing logic takes time, acknowledge first and handle the event asynchronously.

If your endpoint does not return a 200 OK, Chowdeck will retry the delivery using an exponential backoff strategy. Design your handler to be idempotent -- processing the same event more than once should produce the same result.

Security best practices

• Verify every signature -- never process a webhook without first verifying the x-chowdeck-signature header
• Use HTTPS -- always use an HTTPS endpoint to encrypt webhook traffic
• Handle retries -- design your endpoint to be idempotent since events may be delivered more than once
• Use environment variables -- store your webhook secret as an environment variable, never hardcode it