Skip to content
MothershipDevelopers

GuidesConfiguring webhooks

Creating a webhook configuration

Subscribe an endpoint on your server to shipment, document, rebill and invoice 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 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"]
}'

Store the secretKey. You need it to verify each request's signature.

The shipment.rebill.* events need a token with permission to read rebills, and the invoice.* events need one with permission to read invoices. Without it, a request that subscribes to one gets 403 MISSING_PERMISSION.

Use an https URL on a domain name, as the dashboard requires. Endpoint requirements lists the addresses Mothership never sends to.

subscribedEvents takes any event from the webhook event catalog. Each event's page lists the keys in its data and shows an example request.