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:
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.
To set up a webhook, you can do so in the Webhook Management page in the Nash Portal. Here, you can filter by event type and add multiple endpoints if you want to send different events to different endpoints, for example. All event schemas and types are enumerated under the Event Catalog tab. Select events will have example payloads. Note that event schemas are assumed to be batch jobs. If your job is not a batch job, there will be no key “batch” and you’ll see "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:
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”.
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 send pickup 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 as well as handles retries.
To verify the webhook, you have a couple of options:
- Use the Svix SDK
- Manually verify
In order to verify you’ll need the signing secret, which can be found in the portal under Settings > Webhooks > Click on an Endpoint > Signing Secret
Retry Policy
A webhook retry is an attempt to send a webhook message that has already failed. Our automatic retry schedule is as follows:
- Immediately
- 5 seconds
- 5 minutes
- 30 minutes
- 2 hours
- 5 hours
- 10 hours
- 10 hours (in addition to the previous)
We also offer manual retries, or you can automatically retry (“Recover”) all failed messages starting from a given date on the Nash Portal.
After the conclusion of the above attempts, the message will be marked as Failed for this endpoint, and you will get a
webhook of type message.attempt.exhausted notifying you of this error.
If all attempts to a specific endpoint fail for a period of 5 days, the endpoint will be disabled, and a webhook (EndpointDisabledEvent) will be sent to your account (not to the failing endpoint).