# About webhooks for event updates with Shipium

Webhooks are a convenient way for your organization to be notified automatically of shipment event updates. You can register for a webhook to be notified of events for each service:

- Carrier selection
- Label generation

You'll need to register a separate webhook for each service – one for carrier selection and one for labels – for which you wish to receive notifications. Once you register a webhook for your organization, the next shipment update for your event will send notifications to the API endpoint for events matching your selected data fields (e.g., `eventType`). You will receive webhook notifications whenever a carrier selection or label is created, updated, or deleted, depending on the webhooks you register.

This document guides you through the steps to register a webhook for your organization for either carrier selection or label generation. You can register for both webhooks to receive updates for both carrier selection and label generation. To start, you’ll need to access the [Shipium Console](https://partner.shipium.com/login). To register a webhook for tracking shipments with Shipium, you can refer to [Webhooks for Tracking](https://docs.shipium.com/docs/webhooks-for-tracking-updates).

## Steps to register your webhook

Within the [Shipium Console](https://partner.shipium.com/login), you'll follow these instructions to register your organization's webhook.

### Step 1. Navigate to Carrier Selection Webhooks

In the navigation pane at left, navigate to **Carrier Selection**, and then **Carrier Selection Webhooks**.

### Step 2. Add new webhook

Select the **Add Webhook** button to the far right of your screen, located near your organization's user account profile information. Any existing webhooks your organization has previously registered will appear on the **Carrier Selection Webhooks** screen. If your organization has no existing registered webhooks, this screen will contain no webhooks until you've registered your first one.

### Step 3. Provide settings information

Complete the required **Settings** fields shown in the **Webhook Detail** screen.

1. **Name.** Provide a descriptive name for your webhook. We suggest using a simple naming convention that uses the underscore symbol to separate each element of your webhook's intended use, such as `{organization}_{action}_{app}_{version}`.
2. **Payload URL.** Create a web app with a Uniform Resource Locator (URL) to use as your webhook to receive shipment event notifications. This is the endpoint deployed on your server to receive incoming webhook shipment events your organization has selected. Enter your Hypertext Transfer Protocol Secure (HTTPS) URL endpoint into the **Payload URL** field.
3. **Status.** You'll use the toggle to set the webhook's status as _Active_ or _Inactive_ to determine if your new webhook will immediately be active once created. Shipium automatically sets new webhooks to inactive by default. This allows your organization to _test your webhook before activating it_ as well as _create a webhook that you may not be ready to activate_. The benefit to your organization is a safe testing environment before the webhook starts sending shipment event notifications to your organization's server.
4. **Tenants.** This field will only appear if your organization uses Shipium's **Tenant** feature. If your organization doesn't use **Tenants**, you can disregard this step.

### Step 4. Add optional headers

For **Headers** you may optionally add custom HTTP endpoint headers to be sent in the webhook event by providing the key and value for the header.

### Step 5. Select event types for notifications

In the **Event Type Select** section, you'll select the event type for which you wish to be notified via the webhook you're creating. You must register a webhook separately for each event type.

### Step 6. Add optional extended data fields

Some carrier selection webhooks can optionally include extended data fields, providing additional context about the shipment. This is particularly useful if you use Shipium for carrier selection but generate labels externally.

### Step 7. Test webhook

Finally, send a test payload to your endpoint. You'll select the **Send Test** button.

## Shipment event types for your webhook

The following table includes the event metadata event types that can be returned for a carrier selection or label event notification. Each event type needs its own webhook registration; however, you can point all registered webhooks at the same API.

| Event type for webhook         | Description                                           |
|--------------------------------|-------------------------------------------------------|
| Carrier Selection Created       | Represents a carrier selection creation                |
| Carrier Selection Updated       | Represents an update to a created carrier selection    |
| Carrier Selection Deleted       | Represents deletion of a carrier selection             |
| Label Created                  | Represents a label creation                            |
| Label Updated                  | Represents an update to a created label               |
| Label Deleted                  | Represents deletion of a label                         |

## Final steps and sample webhook call content

This section provides instructions for responding successfully to your webhook's initial call as well as sample webhook messages as they would appear as incoming shipment event updates.

### How to respond to your first webhook call

Once you've successfully registered your organization's webhook, you will start receiving webhook calls. Upon receipt of your webhook call, you'll need to respond with an appropriate Hypertext Transfer Protocol (HTTP) status code to acknowledge successful receipt of your webhook call. Your response must:

- be an HTTP status code within the 200-299 range; and
- be delivered within 3 seconds of receiving the webhook call.