---
updatedAt: 2025-11-11T23:07:06.000Z
agentTools:
  projectIndex: https://developers.shipup.co/llms.txt
---

# Receiving webhooks

For an introduction to Shipup webhooks, please read the guide [here](https://developers.shipup.co/docs/webhooks). This documentation is a reference for the different webhook settings and fields.

## Webhook event format

When an event corresponding to your webhook settings' webhook event type occurs, Shipup will send a JSON formatted webhook event to the endpoint specified in your webhook settings using the following format:

<Table align={["left","left"]}>
  <thead>
    <tr>
      <th>
        FIELD
      </th>

      <th>
        DESCRIPTION
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        **id**
        integer
      </td>

      <td>
        Unique identifier of the webhook event
      </td>
    </tr>

    <tr>
      <td>
        **object**\
        string
      </td>

      <td>
        Object type. Will always be <code>webhook\_event</code> for this object
      </td>
    </tr>

    <tr>
      <td>
        **data**\
        object
      </td>

      <td>
        Data of the webhook event. See format below
      </td>
    </tr>

    <tr>
      <td>
        **livemode**\
        boolean
      </td>

      <td>
        Has the value <code>true</code> for production data and the value <code>false</code> for test data.
      </td>
    </tr>

    <tr>
      <td>
        **retry\_count**\
        integer
      </td>

      <td>
        Webhook event POST retry count. This counter starts at 0 and will increase as the webhook fails being sent
      </td>
    </tr>

    <tr>
      <td>
        **type**\
        string
      </td>

      <td>
        Type of webhook. See table above for the different type codes
      </td>
    </tr>

    <tr>
      <td>
        **created\_at**\
        datetime
      </td>

      <td>
        Time at which the webhook was created. Will not be updated afterwards and will be prior to the time the webhook is actually sent
      </td>
    </tr>
  </tbody>
</Table>

The <code>data</code> field object of the webhook event will have the following format:

<Table align={["left","left"]}>
  <thead>
    <tr>
      <th>
        FIELD
      </th>

      <th>
        DESCRIPTION
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        **object**
        object
      </td>

      <td>
        Root object of the webhook event. For example if the <code>webhook\_event\_type\_code</code> field of the webhook event is <code>tracker.events.new</code>, the root object will be a tracker
      </td>
    </tr>

    <tr>
      <td>
        **reason**\
        object
      </td>

      <td>
        Information about what triggered the webhook event. For example if the <code>webhook\_event\_type\_code</code> field of the webhook event is <code>tracker.events.new</code>, the reason will contain the ID of the tracker's new event
      </td>
    </tr>
  </tbody>
</Table>

## Authentication

It is possible to configure several ways in which the webhook call will be authenticated

### BASIC HTTP Auth

[Basic HTTP Auth](https://en.wikipedia.org/wiki/Basic_access_authentication) with a username and a password that will be sent encoded with base64 encryption.

| FIELD        | DESCRIPTION                 |
| :----------- | :-------------------------- |
| **username** | Username for authentication |
| **password** | Password for authentication |

### Oauth 2.0 - JWT Bearer Flow

One of the many flows inside the [Oauth 2.0](https://en.wikipedia.org/wiki/OAuth) specification. This is compatible with [Google IAP](https://cloud.google.com/security/products/iap?hl=en).

| FIELD            | DESCRIPTION                                                                                                                                                                                                                                                                                                                                                                            |
| :--------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Audience**     | The audience represents the intended recipient of the JWT. It typically refers to the OAuth 2.0 server or the specific resource server that the JWT is intended for. When the JWT is issued, the audience field specifies who the JWT is intended for. For example, if the JWT is meant for accessing a particular API, the audience would be the URL of that API.                     |
| **Auth URL**     | The Authorization URL is the endpoint where the client initiates the OAuth 2.0 authorization process by redirecting the user's browser to this URL. It will be used to obtain the JWT Bearer Token.                                                                                                                                                                                    |
| **Client Email** | In some cases, particularly when using OAuth 2.0 with service accounts, a client email may be used to uniquely identify the client application. This email is associated with the client credentials (e.g., client ID and client secret) and may be required for authentication and authorization purposes.                                                                            |
| **Client ID**    | The client ID is a public identifier for the client application, typically issued by the OAuth 2.0 server during client registration. It is used by the server to identify the client application making requests. Along with the client secret (if applicable), the client ID is used to authenticate the client application during the OAuth 2.0 flow.                               |
| **Private Key**  | The private key is a part of asymmetric cryptography, which involves a pair of keys: a public key and a private key. These keys are mathematically related in such a way that data encrypted with the public key can only be decrypted with the corresponding private key, and vice versa. In the context of JWT, the private key is used to generate a digital signature for the JWT. |

## Custom HTTP headers

It is also possible to include custom HTTP headers that will be sent with each Webhook request.

> 📘 If a custom header regarding authorization is added at the same time as an authentication method, the custom header will be overwritten with the actual authentication.