type— the kind of event:delivery,task,courier_location, orshift.event— the specific status within that type (enumerated below).data— fordeliveryandtaskevents, a Job (delivery) object, the same shape as the Create Job response (see the example below); forshiftevents, a small payload described in shift.dispatched.
Event schemas assume a batch job. For a non-batch job, the
data object has no batch key and "isBatch": false.Delivery events
Type:delivery
Frequency: once per state transition (e.g., from created -> assigned_driver, or dropoff_arrived-> dropoff_complete)
Guaranteed events: created, assigned_driver, pickup_enroute, pickup_arrived, dropoff_enroute, dropoff_arrived, dropoff_complete (guaranteed events may be inferred from future events)
Events:
Delivery events
Task events
Type:task
Frequency: once per state transition (e.g., from running -> completed)
Events:
Courier location events
Type:courier_location
Events:
updated
All timestamps are UTC, ISO 8601 with microseconds and no timezone suffix (for example
2022-03-05T01:11:51.078927).Webhook response
Best practices
Nash jobs can include multiple delivery attempts (see Jobs overview). When processing our webhook updates, make sure a cancellation or failure on one task doesn’t disrupt your handling of the job’s other tasks. Furthermore, since there are multiple tasks, you should be prepared to handle multiple instances of the same webhook event. For example, if a job has two tasks — one assigned to Provider A and another to Provider B — both providers might sendpickup_arrived events. Refer to Delivery events for more details on the guaranteed statuses we will send.
You should also be prepared for some providers erroneously sending statuses such as pickup_complete or
dropoff_complete when their drivers have not completed a delivery yet.
Verifying webhooks
We use a service called Svix to send webhooks. Svix prevents attacks and forgeries by signing webhook requests, and also handles retries.How to verify
To verify the webhook signature and ensure the request genuinely came from Nash via Svix, you have a couple of options:- Use the Svix SDKs: The recommended approach is to use the official Svix SDKs for your language/framework. These libraries handle signature verification and timestamp checks automatically.
- Manually Verify: You can manually verify the signature using the request headers (
svix-id,svix-timestamp,svix-signature) and your endpoint’s signing secret. You will also need to implement the timestamp check yourself to prevent replay attacks.
Firewall configuration (static IP addresses)
If your webhook receiving endpoint is behind a firewall or NAT, you may need to explicitly allow traffic from Svix’s IP addresses. Webhooks will originate from the IP addresses listed in Svix’s source IPs documentation.Retry policy
A webhook retry is an attempt by Svix to re-send a webhook message that previously failed to be delivered to your endpoint (e.g., due to a network error, server error (5xx), or certain 4xx errors like 408, 409, 429 on your end). Our automatic retry schedule is approximately as follows:- Immediately
- 5 seconds
- 5 minutes
- 30 minutes
- 2 hours
- 5 hours
- 10 hours
- Another 10 hours
Stop retries or disable an endpoint
Include thewebhook-delivery header in your response when you need to override the normal delivery behavior:
webhook-delivery: abort-messagestops remaining retries for the current message. It has no effect on a successful response because any2xxresponse already marks the message as delivered.webhook-delivery: disabledisables the entire endpoint and stops all future webhook deliveries until the endpoint is re-enabled. Use it only when the endpoint should no longer receive events.
410 Gone also disables the endpoint. See Svix’s delivery control documentation for details.
You can also manually trigger retries for specific messages or automatically retry (“Recover”) all failed messages starting from a given date via the Nash Portal (Webhook Management > Select Endpoint > Attempts).