Skip to main content
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

By default an account has one outgoing webhook endpoint. Additional endpoints can be enabled for your account by your account team.

​
Delivery

​
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.

​
Triggers and filters

A webhook notification is created in the Notification Center with Webhook as the channel and your endpoint as the destination. 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. 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

​
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