GuidesConfiguring webhooks

Creating a webhook configuration

Subscribe an endpoint on your server to shipment and document events.

1 min read

Organizations can subscribe to any of the events listed below via the Create a webhook configuration endpoint, or on the Webhooks settings page in the dashboard.

A subscription to the shipment.purchased and billOfLading.created events can be set with the following request.

curl --request POST \
  --url https://api.mothership.com/beta/webhookConfigs \
  --header "Authorization: Bearer $MOTHERSHIP_API_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
  "webhookUrl": "https://www.yourserver.com/webhook/mothership",
  "subscribedEvents": ["shipment.purchased", "billOfLading.created"]
}'

{
  "data": {
    "id": "48asjgaoi33nkl4t3lae",
    "createdAt": "2019-03-20T16:17:13.424Z",
    "status": "active",
    "subscribedEvents": ["shipment.purchased", "billOfLading.created"],
    "webhookUrl": "https://www.yourserver.com/webhook/mothership",
    "secretKey": "de3ADDAek3245DLAdANe91Dn3asklAMSsna03aGKkl23agsJea"
  }
}

Store the secretKey. You need it to validate webhook payloads.

The webhookUrl must be an https URL on a domain name. Mothership doesn't send webhooks to http URLs, IP addresses or localhost.

Webhook event type	Sent when
billOfLading.created	A bill of lading is first attached to a shipment.
billOfLading.updated	A new version of a bill of lading is attached.
proofOfDelivery.created	A proof of delivery is first attached.
proofOfDelivery.updated	A new version of a proof of delivery is attached.
deliveryReceipt.created	A delivery receipt is first attached.
deliveryReceipt.updated	A new version of a delivery receipt is attached.
certificateOfInsurance.created	A certificate of insurance is attached.
shipment.purchased	A shipment is booked.
shipment.status.updated	A shipment's status changes.