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_changedstring
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 theX-Webhook-Signature header. Always verify this signature to ensure the request came from Chidori.
The signature format is: t={timestamp},v1={signature}
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.
