# Creating a webhook configuration

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

Organizations can subscribe to any of the events listed below via the [Create a webhook configuration](https://developers.mothership.com/reference/createwebhookconfig) endpoint, or on the [Webhooks settings page in the dashboard](https://dashboard.mothership.com/settings/webhooks).

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

```curl
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"]
}'
```

```json 201 Response
{
  "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](https://developers.mothership.com/docs/webhooks-validation).

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

> [!NOTE]
> Refer to our [webhooks reference](https://developers.mothership.com/reference/webhooks) for detail on webhook payload schemas.

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

> [!NOTE] Multiple webhook configs
> Organizations can create many webhook configurations to support handling different event types with different endpoints.

> [!WARNING]
> Note that webhook configurations are scoped to the underlying organization rather than to the developer account through which they were created. An endpoint registered by any account associated with an organization will receive all events corresponding to its webhook configuration.