For an introduction to Shipup webhooks, please read the guide here. This documentation is a reference for the different webhook settings and fields.
Here is the list of webhook event types that you can register:
| TYPE | DESCRIPTION |
|---|---|
tracker.new | Sent when a new tracker is received by Shipup |
tracker.events.new | Sent when a new shipping event is retrieved for a tracker |
notification.new | Sent when a notification is generated |
feedback.new | Sent when a feedback is generated |
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:
| FIELD | DESCRIPTION |
|---|---|
| id integer | Unique identifier of the webhook event |
| object string | Object type. Will always be webhook_event for this object |
| data object | Data of the webhook event. See format below |
| livemode boolean | Has the value true for production data and the value false for test data. |
| retry_count integer | Webhook event POST retry count. This counter starts at 0 and will increase as the webhook fails being sent |
| type string | Type of webhook. See table above for the different type codes |
| created_at datetime | Time at which the webhook was created. Will not be updated afterwards and will be prior to the time the webhook is actually sent |
The data field object of the webhook event will have the following format:
| FIELD | DESCRIPTION |
|---|---|
| object object | Root object of the webhook event. For example if the webhook_event_type_code field of the webhook event is tracker.events.new, the root object will be a tracker |
| reason object | Information about what triggered the webhook event. For example if the webhook_event_type_code field of the webhook event is tracker.events.new, the reason will contain the ID of the tracker's new event |
Authentication
It is possible to configure several ways in which the webhook call will be authenticated
BASIC HTTP Auth
Basic HTTP Auth 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 specification. This is compatible with Google IAP.
| 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.