Skip to main content

Overview

Webhooks allow you to receive real-time HTTP notifications when a delivery status changes. Instead of polling the API for updates, Chidori pushes status updates directly to your server.
Webhooks are configured through the Chidori Dashboard. You can set your webhook URL and manage your signing secret from the dashboard.

How webhooks work

1

Configure webhook in dashboard

Go to chidori.africa/dashboard and set your webhook URL in the settings.
2

Delivery status changes

When a delivery status changes (e.g., ASSIGNED, PICKED_UP, DELIVERED), Chidori creates a webhook payload.
3

Payload delivered

Chidori sends an HTTP POST request to your webhook URL with the event data.
4

Verify and process

Your server verifies the signature and processes the event.

Webhook events

Subscribe to the events you need when configuring your webhook in the dashboard.

Delivery statuses

Webhook payload

All webhook payloads follow this structure:

Payload fields

string
Unique identifier for this webhook event
string
Always delivery.status_changed
string
ISO 8601 timestamp when the event occurred
object

checkout.paid payload

Sent when a customer completes payment on a hosted checkout. Use it to reconcile against your externalReference and to know fulfillment has started.
In delivery-only checkouts goods is empty and breakdown.goodsTotal is 0. The delivery referenced by deliveryId is auto-created and already paid.

Signature verification

Every webhook request includes a signature in the X-Webhook-Signature header. Always verify this signature to ensure the request came from Chidori. The signature format is: t={timestamp},v1={signature}
Always verify webhook signatures in production. Never trust webhook data without verification.

Best practices

Respond quickly

Return a 200 response immediately, then process the event asynchronously.

Handle duplicates

Webhooks may be retried. Use the event id to handle duplicate events.

Use HTTPS

Your webhook URL must use HTTPS for security.

Log everything

Log all webhook events for debugging and audit purposes.

Retry policy

If your webhook endpoint returns an error (non-2xx status), Chidori will retry the delivery:
  • Retry attempts: Up to 3 retries
  • Retry intervals: 1 second, 5 seconds, 30 seconds
  • Timeout: 10 seconds per request

Example: Update order status

Webhook configuration

Webhooks are managed through the Chidori Dashboard:

Configure Webhooks

Set your webhook URL and view your signing secret in the dashboard.