Skip to content
MothershipDevelopers

API referenceWebhooks

Create a webhook configuration

Creates a webhook configuration for your shipper account.

POST/webhookConfigs
Environment
https://sandbox.api.mothership.com/beta
curl --request POST \
  --url 'https://sandbox.api.mothership.com/beta/webhookConfigs' \
  --header "Authorization: Bearer $MOTHERSHIP_API_TOKEN" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "webhookUrl": "https://www.yourserver.com/webhook/mothership",
  "subscribedEvents": [
    "shipment.purchased",
    "billOfLading.created",
    "proofOfDelivery.created"
  ]
}'
Reads your token from $MOTHERSHIP_API_TOKEN
Response
{
: {
: "48asjgaoi33nkl4t3lae",
: "2019-03-20T16:17:13.424Z",
: "active",
: [
"shipment.purchased",
"billOfLading.created",
"proofOfDelivery.created"
],
: "https://www.yourserver.com/webhook/mothership",
: "de3ADDAek3245DLAdANe91Dn3asklAMSsna03aGKkl23agsJea"
}
}

Hover a key to see what it means. Click it to jump to the field.

The SHA256 signature of each payload can be found in the X-Mothership-Signature header of the webhook POST request and verified using the secretKey available on the Create Webhook Config response body. See Validating webhook payloads for more information.

webhookUrl must be an https URL on a domain name, not an IP address or localhost.

Authorization

Authorization: Bearer <token>

Your sandbox API token. See Authentication.

Request body

application/json · required
  • webhookUrlstringRequired

    URL that Mothership POSTs webhook events to.

  • subscribedEventsarray of stringsRequired

    Events that trigger a webhook.

    billOfLading.createdbillOfLading.updatedproofOfDelivery.createdproofOfDelivery.updateddeliveryReceipt.createddeliveryReceipt.updatedcertificateOfInsurance.createdshipment.purchasedWhat each value means →

Responses

    • dataobjectRequired
      • idstringRequired

        ID of the webhook configuration.

      • createdAtstring<date-time>Required

        When this webhook configuration was created, as an ISO 8601 date-time.

      • statusstringRequired

        Current status of the webhook config

        activeinactive
      • subscribedEventsarray of stringsRequired

        Events that trigger a webhook.

        billOfLading.createdbillOfLading.updatedproofOfDelivery.createdproofOfDelivery.updateddeliveryReceipt.createddeliveryReceipt.updatedcertificateOfInsurance.createdshipment.purchasedWhat each value means →
      • webhookUrlstringRequired

        URL that Mothership POSTs webhook events to.

      • secretKeystringRequired

        Secret key for this webhook configuration, used to validate incoming webhook payloads.

What's next

Receiving webhook requests

What each request looks like and how retries work.

Validating webhook payloads

Check every request’s signature with secretKey.