Webhooks

Webhooks provide a mechanism for you to receive real-time notifications about events occurring within the Relay Deliveries system. Instead of constantly polling for updates, your configured endpoint will receive an HTTP POST request whenever a specified event takes place, such as a package being picked up or delivered.

Setting up Your Webhook

To start receiving webhook notifications, you need to configure your webhook URL. This is the endpoint on your server that will listen for and process incoming webhook events.

You can set up or update your webhook URL on the Chowdeck Dashboard:

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

Webhook Events

Relay Deliveries currently provides notifications for the following key events:

• ORDER_AWAITING_PICKUP: Triggered when a rider has arrived and is waiting to pick up the order.
• ORDER_PICKED_UP: Triggered when rider has picked up the order.
• ORDER_ARRIVED_AT_CUSTOMER_LOCATION: Triggered when the rider has arrived at the customer's location.
• ORDER_COMPLETE: Triggered when an order has been delivered to the customer.
• ORDER_CREATED: Triggered when an order has been created.
• ORDER_ASSIGNED: Triggered when an order has been assigned to a rider.

Webhook Payload Structure

Each webhook notification will be an HTTP POST request to your configured URL with a JSON payload in the request body. The payload will generally include:

• category: A string indicating the type of event that occurred (e.g., ORDER_AWAITING_PICKUP).
• description: A string indicating the meaning of the event received.
• payload: An object containing event-specific details. The structure of this payload object will vary depending on the event_type.

Verify Signature

To ensure webhook authenticity, all webhook requests include a signature header x-chowdeck-signature. You must verify this signature using your webhook secret

Steps

1. Retrieve the X-Signature header.
2. Compute an HMAC SHA-256 digest using your webhook secret.
3. Compare the computed digest with the received signature.
4. Reject the request if the signatures do not match.

Example (Node.js)

JavaScript

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')
  );
}

Security Best Practices

To ensure the security and integrity of your webhooks, we recommend:

1. Verify Signatures: Implement a mechanism to verify the signature included in the webhook request headers. This ensures that the request truly originated from Chowdeck and has not been tampered with.
2. HTTPS Only: Always use HTTPS for your webhook URL to encrypt communication.
3. Idempotency: Design your endpoint to be idempotent. This means that processing the same webhook event multiple times will have the same effect as processing it once. This helps handle potential retries from our system.
4. Respond Quickly: Your endpoint should respond with a 200 OK status code as quickly as possible to acknowledge receipt of the webhook. If your processing takes longer, consider queuing the event for asynchronous processing.

Error Handling and Retries

If your webhook endpoint does not respond with a 200 OK status code (e.g., due to an error, timeout, or non-2xx status), Chowdeck will attempt to retry the delivery of the webhook. Retries typically occur with an exponential back-off strategy. Ensure your system is designed to handle duplicate events due to these retries.