> ## Documentation Index > Fetch the complete documentation index at: https://developers.perform.ai/llms.txt > Use this file to discover all available pages before exploring further. # Webhooks > Outgoing webhooks that push a signed shipment update to your endpoint each time Perform.AI processes new events, for integration teams. **Available to all Perform.AI customers.** ## Summary Outgoing webhooks send a shipment update to an HTTPS endpoint you own every time Perform.AI processes new events for a shipment. Your order management, customer service or warehouse system receives the full shipment with its latest events as soon as they are known, without polling the API. ## Who it’s for Integration and engineering teams who need delivery status inside their own systems: updating an order status, opening a customer service case on a failed delivery, or feeding an internal dashboard. Webhooks replace scheduled API polling with a push on every change. ## Key benefits * **Push on every update cycle.** One webhook is sent when a shipment receives new events, even if those events satisfy several activated triggers. The `trigger` field lists every trigger that matched. * **The whole shipment in each message.** The JSON payload carries the shipment, its order and addresses, the latest event, the new events of this cycle and the full event history, so your system does not have to call back for context. * **Signed messages.** Every request carries an HMAC-SHA256 signature of the body, computed with the Authentication Key from your webhook configuration, so you can verify that a message came from Perform.AI. * **Retries when your endpoint is down.** If your endpoint does not answer with HTTP 200, Perform.AI resends the webhook. * **Triggers and filters you choose.** Send on every event or only on the milestones you select, and limit a notification to given carriers, Tracking Pages or shipment tags. ## How it works ### Endpoint | Setting | Rule | | - | - | | Webhook endpoint name | Required. | | Endpoint URL | A valid HTTPS URL that accepts a POST. Before the endpoint is saved, Perform.AI sends a sample payload to it to validate that it can receive and process a message. | | HMAC Authentication key | The key used to sign every webhook. HMAC is the default authentication method. If you need another method, ask your account team. | By default an account has one outgoing webhook endpoint. Additional endpoints can be enabled for your account by your account team. ### Delivery | Aspect | Rule | | - | - | | Method and format | HTTPS POST with a JSON body. | | Expected response | HTTP 200. | | Frequency | One webhook per shipment per update cycle, listing all triggers satisfied in that cycle. | | Retries | If no 200 is received, the webhook is resent up to three times, five minutes apart. After the third retry it is not resent. | ### Authentication Each request includes an `HTTP-X-Hmac-SHA256` header. Its value is the HMAC-SHA256 of the request body, keyed with the Authentication Key from your webhook configuration. To verify a message, compute the same HMAC over the body you received and compare it with the header. A match means the message was sent by Perform.AI. Verification code samples are in the Developers guide: [Webhooks](https://developers.perform.ai/guides/webhooks.md). ### Triggers and filters A webhook notification is created in the Notification Center with Webhook as the channel and your endpoint as the destination. | Setting | Rule | | - | - | | Notification name | Required. Up to 32 characters. | | Trigger | A trigger category from the list, shown with its event types. | | Filters | Optional. Carrier, Tracking Page or shipment tags. | | Endpoint | The configured endpoint to send to. | When more than one trigger matches the same tracking event, only the highest-priority trigger sends, which prevents duplicate webhooks for one update. Beyond event-based triggers, your account may support time-based triggers, such as collection reminders, no-update alerts and post-delivery feedback requests, depending on its configuration. Ask your account team to enable them. ### Payload formats The payload format is set per account. Ask your account team which version your account is on. | Format | What it carries | | - | - | | 5.0 | The shipment: identifiers, carrier, status, current phase, tags, notification contacts, Tracking Page reference, order, addresses, value and costs, dimensions and weight, linked shipments, expected delivery, documents, custom fields, and the `latest_event`, `new_events` and `all_events` views. Reference: [Shipment update v5.0](https://developers.perform.ai/api-reference/webhooks/shipment-update-v5-0.md). | | 5.2 | Everything in 5.0 plus richer shipment objects: line items, delivery rating, returns and collection point details. Reference: [Shipment update v5.2](https://developers.perform.ai/api-reference/webhooks/shipment-update-v5-2.md). | | 5.3 | Everything in 5.2 plus expected delivery split by source and Performance Aspiration results. Reference: [Shipment update v5.3](https://developers.perform.ai/api-reference/webhooks/shipment-update-v5-3.md). | Timestamps are in the form `yyyy-mm-ddThh:mm:ss+00:00`. Dimensions are returned in centimetres, weight in grams, and money as an amount with an ISO 4217 currency code. The `event_key`, `phase` and `phase_key` of an event can be null when the carrier sent an event that has not yet been mapped to a Perform.AI standard event. ## Set up in the portal Configure the endpoint first, then create a notification that sends to it. 1. Go to **Integrations** > **Webhooks** and select **Configure**. 2. Enter the **Webhook endpoint name**, the **Endpoint URL** and the **HMAC Authentication key**, then select **Save**. Perform.AI sends a sample payload to the URL to validate it, so the endpoint must be live. 3. Select **Activate** on the endpoint. 4. Go to **Post-Purchase** > **Notifications** and select **Add Notification**. 5. Select **Webhook** as the communication channel. 6. Enter a notification name (up to 32 characters) and choose the trigger category. 7. Add any carrier, Tracking Page or tag filters, and select the endpoint. 8. Select **Save**, then **Activate**. ## Use via API and MCP * Developers guide: [Webhooks](https://developers.perform.ai/guides/webhooks.md), including signature verification and testing. * Payload reference: [Shipment update v5.0](https://developers.perform.ai/api-reference/webhooks/shipment-update-v5-0.md), [v5.2](https://developers.perform.ai/api-reference/webhooks/shipment-update-v5-2.md) and [v5.3](https://developers.perform.ai/api-reference/webhooks/shipment-update-v5-3.md). * To fill gaps after an outage, query [List shipments](https://developers.perform.ai/guides/list-shipments.md) for shipments updated in the affected window. ## FAQ ### How do I know which payload version I receive? The format is set on your account, not per endpoint. Ask your account team which version applies, and build your parser to ignore fields it does not know so that a later format does not break it. ### Will I get one webhook per trigger? No. When a shipment receives new events, one webhook is sent for that update cycle. The `trigger` field lists the triggers that were satisfied. ### What happens if my endpoint is down? Perform.AI resends the webhook up to three times, five minutes apart. If the third retry also fails, the webhook is not resent. If the data is still available, your account team can arrange for failed webhooks to be resent on the next business day after the incident is resolved. ### Can I use OAuth or another authentication method instead of HMAC? HMAC is the default. Other methods, such as OAuth, JWT or SOAP-based authentication, can be requested through your account team. ### Can I send webhooks to more than one system? By default an account has one endpoint. Your account team can enable additional endpoints. ## Troubleshooting | Symptom | Cause | Fix | | - | - | - | | The endpoint cannot be saved | The URL did not accept the sample payload | Make sure the endpoint is live, accepts an HTTPS POST and returns HTTP 200, then save again. | | No webhooks arrive | The endpoint or the webhook notification is not activated | Activate the endpoint under **Integrations** > **Webhooks** and the notification under **Post-Purchase** > **Notifications**. | | Webhooks arrive for only some shipments | Carrier, Tracking Page or tag filters on the notification exclude the rest | Edit the notification filters or remove them. | | The signature check fails | The HMAC was computed over a modified body, or with a different key | Compute HMAC-SHA256 over the raw request body with the Authentication Key from your webhook configuration. | | Webhooks stopped after an outage and the updates are missing | Retries were exhausted while the endpoint was down | Fix the endpoint, query List shipments for the window, and ask your account team whether the failed webhooks can be resent. | ## Related * [Delivery Notifications](https://developers.perform.ai/products/post-purchase/delivery-notifications.md) * [Klaviyo](https://developers.perform.ai/products/integrations/klaviyo.md) * [Data Integration](https://developers.perform.ai/products/platform/data-integration.md) * [Integrations overview](https://developers.perform.ai/products/integrations/overview.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.