> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usenash.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Nash exposes two MCP servers. The docs MCP server at https://docs.usenash.com/mcp searches this documentation and needs no credentials. The Nash MCP server at https://mcp.usenash.com/mcp operates an organization's deliveries and needs a Nash API key. See https://docs.usenash.com/reference/build-with-ai.
> Use the Sandbox environment (https://api.sandbox.usenash.com/v1) for anything that creates or dispatches deliveries during development.

# Webhooks

> Set up and consume Nash webhooks: event types, payload shape, signature verification, and retries.

Webhooks push real-time delivery events to your endpoint, so you don't have to poll for what Nash already knows. If your application reacts to delivery progress — updating a customer, advancing an order, alerting on a problem — subscribe to webhooks.

Every webhook payload carries three fields:

* `type` — the kind of event: `delivery`, `task`, `courier_location`, `courier_name`, or `shift`.
* `event` — the specific status within that type (enumerated below).
* `data` — for `delivery` and `task` events, a Job (delivery) object, the same shape as the [Create Job](https://docs.usenash.com/api-reference/job/create-job.md) response (see the example below); for `shift` events, a small payload described in [shift.dispatched](https://docs.usenash.com/reference/shift-dispatched-event.md).

Set up endpoints in the [Webhook Management](https://portal.usenash.com/settings/webhook-management) page in the Nash Portal. You can filter by event type and register multiple endpoints — for example, routing different events to different services. The **Event Catalog** tab enumerates every event schema and type, with example payloads for select events.

> [!NOTE]
>
> Event schemas assume a batch job. For a non-batch job, the `data` object has no `batch` key and `"isBatch": false`.

Webhooks work in both sandbox and production. Failed webhook deliveries are retried per our [retry policy](https://docs.usenash.com/reference/webhooks.md#retry-policy), and every request is [signed so you can verify it](https://docs.usenash.com/reference/webhooks.md#verifying-webhooks).

## 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:

```text Delivery events theme={"dark"}
created
not_assigned_driver
assigned_driver
started
pickup_enroute
pickup_arrived
items_pick_update
items_pick_complete
pickup_complete
dropoff_enroute
dropoff_arrived
dropoff_complete
canceled_by_provider
return_in_progress
return_arrived
returned
scheduled
expired
failed
canceled_by_customer
canceled_by_nash
canceled_by_auto_reassign: this is triggered when using the auto-reassignment functionality in Dispatch Settings / Dispatch Strategies
proof_of_delivery: proof(s) of delivery have been added/updated in the `delivery.proofOfDelivery` field
pincode_verification: pincode of delivery when pincode is requested. it will be updated in the `delivery.proofOfDelivery` field
pickup_label: available if a pickup label is configured to be generated for your account
shipping_label: (SHIPPING ONLY) shipping label has been added/updated in the `delivery.documents` field
manifested: (SHIPPING ONLY) shipment has been manifested and manifest document has been added/updated in the `delivery.documents` field
```

### Where a scan happened

Shipping carriers that scan a parcel through their network report where each scan took place — a sorting facility, a depot, a suburb. Each entry in the delivery's `statusHistory` carries that as `location`, alongside `status` and `statusDescription`:

```json theme={"dark"}
"statusHistory": [
    {
        "createdAt": "2026-08-04T02:55:27.240246",
        "status": "in_transit",
        "statusDescription": "Item processed at sorting facility",
        "location": "WELSHPOOL WA"
    }
]
```

`location` is `null` when the provider reported no location for that transition, which is the normal case for point-to-point couriers — they move a parcel directly rather than through scan points. Use it to tell a customer where their parcel is between the pickup and the doorstep, rather than only that it's moving.

## Task events

**Type**: `task`

**Frequency**: once per state transition (e.g., from `running` -> `completed`)

Events:

```text theme={"dark"}
created
updated
running
completed
canceled_by_provider
failed
canceled_by_customer
canceled_by_nash
canceled_by_auto_reassign: the task was canceled because a dispatch strategy reassigned the job
canceled_by_reassign: the task was canceled because someone reassigned the job by hand
dispatch_failure
planned_selection
refund_created
refund_updated
```

## Courier location events

**Type**: `courier_location`

Events:

* `updated`

**Frequency**: once every 1-2 minutes (if courier\_location is available). For organizations with immediate location webhooks turned on, one is sent as each driver position arrives, at most once every 20 seconds per delivery — several times the volume, so the endpoint has to keep up.

Here's a sample response that you can expect from our webhook for an ongoing delivery:

> [!NOTE]
>
> All timestamps are UTC, ISO 8601 with microseconds and no timezone suffix (for example `2022-03-05T01:11:51.078927`).

```json Webhook response theme={"dark"}
{
    "type": "courier_location",
    "event": "updated",
    "data": {
        "id": "job_R7FXJrfB99bpvpzf6CriJC",
        "createdAt": "2022-03-05T01:11:51.078927",
        "portalUrl": "https://portal.usenash.com/active/job_R7FXJrfB99bpvpzf6CriJC",
        "externalIdentifier": null,
        "jobMetadata": {},
        "isActive": false,
        "isBatch": false,
        "jobConfigurations": [
            {
                "package": {
                    "description": "Test package description",
                    "pickupEndTime": null,
                    "pickupStartTime": "2022-03-05T01:16:51",
                    "dropoffStartTime": null,
                    "dropoffEndTime": null,
                    "valueCents": 100,
                    "taxCents": 950,
                    "serviceFeeCents": null,
                    "itemsCount": 1,
                    "pickupLocation": {
                        "id": "loc_dB4x4pToexhgRvGhZSTHaQ",
                        "address": "185 University Ave, Palo Alto, CA 94301",
                        "formattedAddress": "185 University Ave, Palo Alto, CA 94301, USA",
                        "addressNumber": "185",
                        "addressFormattedStreet": "University Ave",
                        "addressCity": "Palo Alto",
                        "addressCountry": "US",
                        "addressState": "CA",
                        "addressZip": "94301",
                        "addressCounty": "Santa Clara County",
                        "businessName": "Test pickup Business",
                        "instructions": "Test pickup Instructions",
                        "firstName": "Test pickup FirstName",
                        "lastName": "Test pickup LastName",
                        "phoneNumber": "+12345679012",
                        "email": null
                    },
                    "dropoffLocation": {
                        "id": "loc_5heYem2xKGfNt9twg33kcT",
                        "address": "401 San Antonio Rd, Mountain View, CA 94040",
                        "formattedAddress": "401 San Antonio Rd, Mountain View, CA 94040, USA",
                        "addressNumber": "401",
                        "addressFormattedStreet": "San Antonio Rd",
                        "addressCity": "Mountain View",
                        "addressCountry": "US",
                        "addressState": "CA",
                        "addressZip": "94040",
                        "addressCounty": "Santa Clara County",
                        "businessName": "Test dropoff Business",
                        "instructions": "Test dropoff Instructions",
                        "firstName": "Test dropoff FirstName",
                        "lastName": "Test dropoff LastName",
                        "phoneNumber": "+12345679019",
                        "email": null
                    }
                },
                "tasks": [
                    {
                        "id": "tsk_7xKGR6PW2pBtuTeRg2b7Bw",
                        "createdAt": "2022-03-05T01:11:51.078927",
                        "status": "COMPLETED",
                        "providerId": "FleetSimulator",
                        "tipAmountCents": 250,
                        "winnerQuote": {
                            "id": "qot_nh5VSwxr4trHsuKHpQbGW6",
                            "providerId": "FleetSimulator",
                            "providerName": "FleetSimulator"
                        },
                        "quotes": [
                            {
                                "id": "qot_nh5VSwxr4trHsuKHpQbGW6",
                                "providerId": "FleetSimulator",
                                "providerName": "FleetSimulator",
                                "providerLogo": "https://nash-provider-logos.s3.amazonaws.com/FleetSimulator.png",
                                "createdTime": "2022-03-05T01:11:52.417462",
                                "expireTime": "2022-03-05T02:11:52.417463",
                                "nashFeeCents": 100,
                                "priceCents": 0,
                                "currency": "USD",
                                "pickupWindow": null,
                                "dropoffEta": "2022-03-05T01:17:52.417416",
                                "tollFeeCents": 0,
                                "insuranceFeeCents": 0,
                                "totalPriceCents": 0
                            }
                        ],
                        "failedQuotes": [],
                        "delivery": {
                            "id": "dlv_MwQDy3s6ajvw5aQ7eQPt7i",
                            "status": "DROPOFF_COMPLETE",
                            "isActive": false,
                            "pickupEta": null,
                            "dropoffEta": "2022-03-05T01:17:52.417416",
                            "dropoffDeadline": null,
                            "currency": "USD",
                            "documents": [
                                {
                                    "id": "doc_ELre5GCELQ6w3UHKAgbm6F",
                                    "type": "SHIPPING_LABEL",
                                    "url": "https://nash-documents-dev.s3-us-west-1.amazonaws.com/dlv_bR7NWwhWSQRohyjs7UZd7D_fEavuZda787M70sJEhtCAA==.png",
                                    "data": null,
                                    "contentType": "image/png"
                                },
                                {
                                    "id": "doc_nuKEL5W8mMgnXuRrFqwwsc",
                                    "type": "PICKUP_LABEL",
                                    "url": "https://nash-documents-dev.s3-us-west-1.amazonaws.com/dlv_bR7NWwhWSQRohyjs7UZd7D_QPiARbKwfJRkC94KVQrT8w==.png",
                                    "data": null,
                                    "contentType": "image/png"
                                }
                            ],
                            "nashFeeCents": 100,
                            "priceCents": 0,
                            "courierName": "Tjy Ifulu",
                            "courierPhoneNumber": "+13408480904",
                            "courierLocation": {
                                "lat": 37.4043247,
                                "lng": -122.1112215
                            },
                            "courierProfileImage":"https://nash-proof-of-delivery-sandbox.s3-us-west-1.amazonaws.com/dlv_SXnvEsXY4aEQ5YVY92sLPK_4t9WSOg3Zw-h4BT0fFUWqw==.jpg",
                            "proofOfDelivery": [
                                {
                                    "type": "photo_proof_of_delivery",
                                    "url": "https://nash-proof-of-delivery-sandbox.s3-us-west-1.amazonaws.com/dlv_SXnvEsXY4aEQ5YVY92sLPK_4t9WSOg3Zw-h4BT0fFUWqw==.jpg",
                                    "size": 12421
                                },
                                {
                                    "type": "barcode_scan",
                                    "text": "pkg_SggEeiudfNRQDvtAF35qPr",
                                    "url": "https://nash-proof-of-delivery-dev.s3-us-west-1.amazonaws.com/dlv_JJUqcMDdxDxoj6Zsk8iru3_rp_nNJtdAVItcnBpKxTHBQ==..png",
                                    "size": 566
                                }
                            ],
                            "statusHistory": [
                                {
                                    "createdAt": "2022-03-05T01:12:00.984078",
                                    "status": "created"
                                },
                                {
                                    "createdAt": "2022-03-05T01:12:16.067396",
                                    "status": "not_assigned_driver"
                                },
                                {
                                    "createdAt": "2022-03-05T01:13:02.459762",
                                    "status": "assigned_driver"
                                },
                                {
                                    "createdAt": "2022-03-05T01:14:32.532602",
                                    "status": "pickup_enroute"
                                },
                                {
                                    "createdAt": "2022-03-05T01:15:17.533789",
                                    "status": "pickup_complete"
                                },
                                {
                                    "createdAt": "2022-03-05T01:16:02.598233",
                                    "status": "dropoff_enroute"
                                },
                                {
                                    "createdAt": "2022-03-05T01:17:32.690484",
                                    "status": "dropoff_arrived"
                                },
                                {
                                    "createdAt": "2022-03-05T01:18:17.945368",
                                    "status": "dropoff_complete"
                                }
                            ],
                            "tollFeeCents": 0,
                            "waitFeeCents": 0,
                            "waitTimeMinutes": 0,
                            "cancellationFeeCents": 0,
                            "returnFeeCents": 0,
                            "insuranceFeeCents": 0,
                            "taxAmountCents": 0,
                            "totalPriceCents": 0
                        },
                        "failureReason": null
                    }
                ]
            }
        ]
    }
}
```

## Reassignments and courier changes

When a job is reassigned, whether by hand, by a dispatch strategy's auto-reassignment, or after a provider cancels, Nash creates a **new task** on the same job rather than editing the old one. Three things follow for a webhook consumer:

* **The old task ends and a new one starts.** The original task emits its terminal event (`task.canceled_by_auto_reassign`, `task.canceled_by_reassign`, `task.canceled_by_provider`, and so on), and the replacement emits `task.created` followed by its own delivery events. Both tasks stay in `jobConfigurations[].tasks`, and nothing on the old task points at its replacement. Treat a task cancellation as terminal for that task only, and read `jobConfigurations[].advancedTask` for the attempt that's now live.
* **Quotes collapse to the winner.** Before a quote is selected, `quotes` lists every offer. Once one is chosen, task and batch payloads carry only the winning quote in `quotes` (`winnerQuote` is unchanged), and `failedQuotes` is never included in a webhook payload.
* **A courier change is not a reassignment.** When the same provider swaps drivers, the delivery's `courierName`, `courierPhoneNumber`, and `courierLocation` update in place and you get a `courier_name` event with `event` set to `updated`, along with the usual `courier_location` updates. No new task, no new quotes.

Each payload is a snapshot of the whole job taken when the change that raised the event was saved, not a diff. Events raised by the same change, such as the cancellation of one task and the creation of its replacement, share one snapshot, so the `data` on a `task.created` event already shows the old task as canceled.

## Best practices

Nash jobs can include multiple delivery attempts (see [Jobs overview](https://docs.usenash.com/api-reference/job/jobs.md)). 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 send `pickup_arrived` events. Refer to [Delivery events](https://docs.usenash.com/reference/webhooks.md#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](https://www.svix.com/) to send webhooks. Svix prevents attacks and forgeries by signing webhook requests, and also handles [retries](#retry-policy).

### How to verify

To verify the webhook signature and ensure the request genuinely came from Nash via Svix, you have a couple of options:

1. **Use the Svix SDKs:** The recommended approach is to use the official [Svix SDKs](https://docs.svix.com/receiving/verifying-payloads/how) for your language/framework. These libraries handle signature verification and timestamp checks automatically.
2. **Manually Verify:** You can [manually verify](https://docs.svix.com/receiving/verifying-payloads/how-manual) 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.

You'll need the **signing secret**, which can be found in the Nash Portal under Settings > Webhook Management > Click on an Endpoint > Signing Secret.

![Where to find your Svix signing secret.](https://mintcdn.com/nashtechnologies/RFBLfoXweHrotTxu/images/portal/svix-signing-secret.png?fit=max\&auto=format\&n=RFBLfoXweHrotTxu\&q=85\&s=5845ee72edeaf66124fee3d9f1464bd0)

### 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](https://docs.svix.com/receiving/source-ips).

## 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

The figure here draws the schedule on three time scales and lets a reader choose how long their endpoint is down. Counted from the event, the tries fall at about: 0 seconds, 5 seconds, 5 minutes, 35 minutes, 2 hours 35 minutes, 7 hours 35 minutes, 17 hours 35 minutes, and 27 hours 35 minutes. An endpoint that is down for 20 minutes misses the first three tries and receives the event on the fourth, about 35 minutes after it happened. If all eight tries fail, the message is marked failed and you can replay it from Webhook Management in the Portal.

Reference: [Svix retry documentation](https://docs.svix.com/retries)

### Stop retries or disable an endpoint

Include the `webhook-delivery` header in your response when you need to override the normal delivery behavior:

* `webhook-delivery: abort-message` stops remaining retries for the current message. It has no effect on a successful response because any `2xx` response already marks the message as delivered.
* `webhook-delivery: disable` disables 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.

Returning HTTP `410 Gone` also disables the endpoint. See [Svix's delivery control documentation](https://docs.svix.com/receiving/delivery-control) 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).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.