System Components
Webhooks
If you are building an application that relies on constant updates for your Nash deliveries, then integrating a Nash webhook will help you receive real-time delivery events.
At Nash, we support a few webhooks types. The webhook response will include 3 fields:
Frequency: once per state transition (e.g., from
Frequency: once per state transition (e.g., from running -> completed)
Events:
Events:
-
typefield. Webhook types can be of typedelivery,task,courier_location.eventfield which can be one of several possible statuses (see below).datafield which is a Job object, similar to the Create Job endpoint or see the example below.
"isBatch": false, both nested under the key “data”.
We support webhooks in both sandbox and production environments. Failed webhook requests will be retried according to our retry policy and are sent securely.
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
type=task:
Frequency: once per state transition (e.g., from running -> completed)
Events:
type=courier_location:
Events:
-updated
Frequency: once every 1-2 minutes (if courier_location is available)
Here’s a sample response that you can expect from our webhook for an ongoing delivery:
Note: All timestamps are in UTC and in this format “%Y-%m-%dT%H:%M:%S.%f”.
Webhook response
Best Practices
Nash jobs can include multiple delivery attempts (see Job Overview). When processing our webhook updates, please ensure that cancellations / failures of one task does not cause issues in your application. 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 Fleet A and another assigned to Fleet B - both fleets might sendpickup arrived events. Refer to this section for more details on the guaranteed statuses we will send.
You should also be prepared for some fleets 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 following IP addresses: https://docs.svix.com/receiving/source-ipsRetry 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