Skip to main content

Setup Webhooks in ChannelDock

Why use webhooks?

ChannelDock provides webhooks to inform your system immediately when something changes in your account. Instead of polling the API on a schedule, you automatically receive a notification when an order is created or updated, a shipment is created, stock levels change or a return is registered. Webhooks help you automate processes and reduce unnecessary API requests.

Key features

  • Event timing: Webhooks fire some minutes after an event occurs, giving you near realtime updates.

  • Payload consistency: The JSON payload of a webhook matches the structure returned by the corresponding API endpoint.

  • Automatic retries: If ChannelDock can’t deliver a webhook, up to five attempts are made with increasing delays (0, 30, 60, 120 and 240 seconds). After ten failed deliveries the webhook is disabled for safety.

  • Security: Each webhook can have its own secret key. ChannelDock uses this secret key to compute a digital signature so you can verify the authenticity of the payload.

Setting up a webhook

  1. Navigate to the settings: Log in to ChannelDock and go to Settings → API & Webhooks. You will see two sections: API keys and Webhooks.

  2. Create a new webhook: Click Create new webhook. A “Webhook Configuration” window appears.

  3. Fill in the fields:

    • Webhook name: Choose a descriptive internal name (for example, “Order updates”).

    • Webhook URL: Enter the URL of your endpoint where ChannelDock may send an HTTP POST request to. Make sure this URL is publicly reachable and responds within 5 seconds.

    • Event to trigger webhook: Select the type of event you want notifications for. Possible events include order.created, order.updated, order.status.changed, order.deleted, shipment.created, stock.updated, return.created, return.handled and return.product.updated.

    • Status: Leave this set to Active. Webhooks are automatically deactivated after 10 failed delivery attempts.

    • Webhook secret (optional but recommended): Provide your own secret or click Generate to create a strong secret. ChannelDock uses this secret to compute an HMAC‑SHA256 hash signature so you can verify the payload.

  4. Save: Click Save webhook. ChannelDock stores your webhook and will send events of the type you selected to your endpoint.

Payload structure and events

When a chosen event occurs, ChannelDock sends a JSON payload to your endpoint. The payload contains at least the following fields:

{ 
  "event": "order.created",
  "payload": { 
    ...
  },
  "signature": "<hash>" (Optional but recommended)
}

  • event – the event for which the webhook was configured (for example order.created).

  • payload – contains details of the order, shipment, return or stock mutation. The structure matches the API response for the corresponding object.

  • signature – only present when a secret is configured. This is an HMAC‑SHA256 signature of the full payload except for the signature field itself.

Verifying the signature

It’s important to ensure that the webhook was sent by ChannelDock and that the payload has not been tampered with. You do this by comparing the signature provided by ChannelDock with your own calculation.

Internally, ChannelDock signs every payload by calculating an HMAC‑SHA256 hash of the JSON data with the secret you configured. The resulting hash is added as the signature field in the payload.

Verifying the signature in your application

  1. Receive the webhook: Parse the JSON and temporarily store the value of the signature field. Remove the signature field from the payload before computing the hash.

  2. Generate a hash: Use your secret key together with the HMAC-SHA256 hash method to create a new signature. Run this on the JSON data you received (without the signature field). 

  3. Compare the hashes: If the hash you computed matches exactly with the signature you received, you can trust that the payload is authentic and unmodified.

Tips for secure processing

  • Assign each webhook its own secret and rotate it regularly.

  • Use a constant‑time comparison function (for example hash_equals in PHP) to prevent timing attacks.

  • Perform additional checks on the contents of the payload (for example verify that the order exists) before executing any actions.

Best practices

ChannelDock recommends several practices to process webhooks safely and reliably:

  • HTTP‑200 response: Let your endpoint return an HTTP 200 OK as soon as the payload has been successfully received. Otherwise ChannelDock sees the attempt as failed and tries again.

  • Idempotency: Webhook messages may sometimes be sent twice (for example due to network issues or retries). Make sure your processing logic is idempotent so duplicate messages don’t cause duplicate work.

  • Monitoring: Use the ChannelDock dashboard to monitor the status of your webhooks and identify any errors.

  • Payload handling: Ensure that your endpoint can handle large payloads and responds within a reasonable time (≤ 5 seconds). Webhooks are automatically deactivated after ten failed deliveries.

Back to top