# Set up my webhooks

## Setup the webhook in your account

1. Ask for your webhook activation to your contact @ shiptify
2. Go to **Settings**
3. Go to **Webhooks** tile inside **My Settings** section
4. Click on <mark style="color:blue;">**+ Add new URL**</mark>
5. Select events to start receiving updates

<figure><img src="/files/wlSaoQDsVEq2ibwZVvz6" alt=""><figcaption><p>Webhook Set Up inside your Shiptify account</p></figcaption></figure>

### Server Codes

For Webhook POSTs, Shiptify listens for the following codes from your server and reacts accordingly:

* If Shiptify receives a **200 (Success)** code it will determine the webhook POST is successful and not retry.
* For any other code, Shiptify will retry POSTing according to the schedule below for Webhooks other than the delivery notification.

{% hint style="info" %}
If your application is unable to process the webhook request but you do not return a 406 error code, Shiptify will retry during 24 hours at the following intervals before stop trying: 0 minutes, 30 minutes, 1 hour, 4 hours and 24 hours.
{% endhint %}

### Securing Webhooks

To ensure the authenticity of event requests, Shiptify signs them and posts the signature along with other webhook parameters.

If you want to verify the requests, please ask your Shiptify account manager about it and follow the process here under.

The **signature** parameters are described in securing webhooks and the **event-data** parameters are the same as described in Event Structure

> ```json
> {
>     "event_type": "create_shipment",
>     "timestamp": 1643117545594,
>     "signature": "string",
>     "token": "string"
> }
> ```

| Parameter | Type   | Description                                                |
| --------- | ------ | ---------------------------------------------------------- |
| timestamp | int    | Number of seconds passed since January 1, 1970.            |
| signature | string | String with hexadecimal digits generate by HMAC algorithm. |
| token     | string | Randomly generated string with length 50.                  |

To verify the webhook is originating from Shiptify you need to:

* Concatenate timestamp and token values.
* Encode the resulting string with the HMAC algorithm (using your Webhook Signing Key as a key and SHA256 digest mode).
* Compare the resulting hexdigest to the signature.
* Optionally, you can cache the token value locally and not honor any subsequent request with the same token. This will prevent replay attacks.
* Optionally, you can check if the timestamp is not too far from the current time.

{% hint style="info" %}
*Note*: Due to potentially large size of posted data, Shiptify computes an authentication signature based on a limited set of HTTP headers.
{% endhint %}

Here’s a sample in Node.js

> ```javascript
> const crypto = require('crypto')
>
> const verify = ({ signingKey, timestamp, token, signature }) => {
>     const encodedToken = crypto
>         .createHmac('sha256', signingKey)
>         .update(timestamp.concat(token))
>         .digest('hex')
>
>     return (encodedToken === signature)
> }
> ```

### Shipment Modes

| Mode Type | ID |
| --------- | -- |
| air       | 1  |
| sea       | 2  |
| road      | 3  |
| rail      | 4  |
| express   | 5  |
| groupage  | 6  |
| courier   | 7  |
| air-sea   | 8  |

### Content Types

You can request an access to the **Production** [Content Types library](https://docs.google.com/spreadsheets/d/1kewQbuQLcAZh-m7nS2PcftU33HH91RqE2BkOEUuD16A/edit#gid=0%20target=) directly with your contact @ Shiptify.

### Auto-test your webhook

When you think you have successfully set up your webhook, you can test it by yourself by creating a test shipment.

You can do so by switching to your <mark style="color:purple;">shipper demo account</mark>. Switch to shipper account by clicking on the top bar icons for accounts.

<figure><img src="/files/JwYktoQ1JK2kjPM5OPhx" alt=""><figcaption><p>Switching account Icon</p></figcaption></figure>

{% hint style="info" %}
The webhook will be triggered **only** if the shipment is **confirmed**. So you will have to confirm it by yourself either on shipper side (**Auto Confirm**) or on carrier side (**Regular carrier confirmation**).
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.shiptify.com/i-am-a-shipper/webhooks/set-up-my-webhooks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.