Receiving webhook requests

Webhook events arrive as POST requests with a JSON body, usually within 1 minute of the triggering event.

Below is an example webhook payload.

{
  "data": {...}, // Webhook event data
  "deliveryAttempt": 1, // Times we have sent this event, including this attempt
  "pendingRetries": 16, // Times we will re-attempt to send this event if this attempt fails
  "eventType": "shipment.purchased",
  "sentAt": "2019-03-19T17:42:59.745Z" // ISOString datetime that we sent this webhook event
}

The contents of data will vary by webhook event type. More information can be found in our webhooks reference.

Responding and retries

Respond with any 2xx status code within 30 seconds to acknowledge an event. Mothership treats any other response, or no response in that time, as a failure and sends the event again, up to 17 attempts in total. The wait between attempts starts at 5 seconds and doubles each time, so retries continue for a few days. Each retry carries the next deliveryAttempt and one fewer pendingRetries.

• Return 2xx quickly and do slow work afterwards.
• Retries mean you can receive the same event more than once, so make your handler safe to run twice for the same event. Every attempt at one event carries the same X-Mothership-Delivery-Id header, so you can skip an id you have already processed.
• Your endpoint must be on the public internet. Mothership doesn't send webhooks to private, loopback or link-local addresses, including through a redirect.
• Validate the signature before trusting the body.