Event Cast API

19 June 2024: Event Cast API - Subscription on customer numbers

Starting June 19, 2024, the Event Cast API will support subscriptions on customer numbers. This new feature complements the existing functionality to subscribe on shipment or parcel numbers and does not replace them.

With customer number subscriptions, you’ll automatically receive updates for all shipments registered on that customer number, removing the need to manage individual subscriptions for each new shipment or parcel. These subscriptions will have a validity of one year.

To start using the new customer number subscription, please see to the updated Event Cast API documentation.

The Event Cast API allows you to subscribe to tracking events for shipments by registering webhooks. There are two types of subscriptions available:

Customer Number Subscription: Event notifications will be sent for all shipments belonging to the subscribed customer number.
Tracking Number Subscription: Event notifications will be sent for the subscribed shipment or parcel number.

Event notifications are automatically pushed to the subscriber as they happen, avoiding the need to repeatedly poll statuses by calling the Tracking API. You define an endpoint that accepts HTTP POST requests, and whenever an event is registered for a subscribed shipment, we send it to the specified URL.

Authentication

To integrate with the Bring APIs, you will need a Mybring user account with an API key. Information about prerequisites and authentication headers can be found on the general API Getting Started page.

Limitations

Maximum 50 concurrent requests per user is allowed. Maximum 10 concurrent requests per user is allowed on the test endpoint. Maximum 100 shipments can be batch created per request. But there is no limitation on how many webhooks you can have in total.

The current version doesn’t support event history, you can use the Tracking API to get a shipment’s full history.

Webhooks cannot be edited after they have been created.

Expiration duration and retry timing are fixed and cannot be configured.

Expired webhooks are not available.

Multiple webhooks for one shipment can only be registered as long as they subscribe to different events.

Formats

REST JSON over HTTP.

Events

Specify the events (event_groups / eventSet) you want to subscribe to as an array with comma separated strings.

Tracking number subscription example

"event_groups": ['IN_TRANSIT', 'NOTIFICATION_SENT', 'TERMINAL']

Customer number subscription example

"eventSet": ['IN_TRANSIT', 'NOTIFICATION_SENT', 'TERMINAL']

We recommend keeping your list as short as possible. By subscribing only to events relevant to you, your server will not get unnecessary HTTP requests from Bring. Wildcards like * and ALL are not supported.

The list of events is subject to change.

Event	Description
`ATTEMPTED_DELIVERY`	Package has been attempted delivered at the door. Depending on the service it will be tried again or sent to closest pickup point.
`CUSTOMS`	Package is in customs clearance.
`COLLECTED`	Package has been collected at pickup address.
`DELIVERED`	Package has been delivered.
`DELIVERED_SENDER`	Package has been returned to the sender.
`DELIVERY_CANCELLED`	Home delivery has been cancelled by the customer.
`DELIVERY_CHANGED`	Date for Home delivery has been changed by customer.
`DELIVERY_ORDERED`	Home delivery has been ordered.
`DEVIATION`	Deviation in production. Something wrong has happened and there is a probability for delay.
`HANDED_IN`	Package has been handed in to Bring.
`INTERNATIONAL`	Package has been sent from origin country or arrived at destination country.
`IN_TRANSIT`	Package is in transit.
`NOTIFICATION_SENT`	Notification for this package has been sent by sms, push and/or mail. This can be informational and action notifications like pickup notice.
`PRE_NOTIFIED`	EDI message for the package has been received by Bring.
`READY_FOR_PICKUP`	Package has arrived at pickup point.
`RETURN`	Package is on its way back to the sender.
`TRANSPORT_TO_RECIPIENT`	Package has been loaded for delivery to the recipient.
`TERMINAL`	Package is now registered/arrived at inbound/outbound storage terminal.

Callbacks

In order to receive requests from Bring, your callback URL must be accessible on the internet and able to receive requests from Bring IPs. You should also provide HTTPS-enabled endpoints and use some kind of authentication mechanism to minimize risk. Do not use self-signed certificates for HTTPS, such requests may fail.

If you need simple authentication while receiving requests from Bring, we recommend using the header functionality provided by the webhook configuration.

All received callbacks from Bring will be using UTC as its current timezone and is based on the following format (Java):

"yyyy-MM-dd'T'HH:mm:ssZ"

Information Bring will provide in the request

HTTP POST payloads that are delivered to your webhook’s configured URL endpoint contains both a JSON with event information and several Bring specific headers:

Header	Description
`X-Bring-Application`	Identifies the application that sent the request to your endpoint
`X-bring-Correlation`	Correlation ID can be used when contacting Bring on error cases
`X-bring-Version`	Indicates the application version
`<your headers>`	Any headers you specified in the webhook configuration

Example callback from Bring to your endpoint

POST /callback/Webhook HTTP/1.1
host: localhost:80
Accept: application/json
User-Agent: Bringcast-Webhook/v1.0.34-SNAPSHOT
X-Bring-Application: BMEC
X-bring-Correlation: xA3n7
X-some-fancy-custom-header: with-some-value-that-I-expect
Content-Type: application/json
Content-Length: 188

{
  "status": "IN_TRANSIT",
  "id": "ad84cbca-2e89-43e0-a301-a8d5d7fe7804",
  "shipment": "SHIPMENTNUMBER",
  "package": "TESTPACKAGEDELIVERED",
  "created": "2019-03-16T14:58:48+0000",
  "pushed": "2019-03-16T14:58:49+0000"
}

Retries

If your endpoint is down and a callback is sent, the API will try to send a request two times with 30 minutes between and a third and final time after another hour.

Endpoints

Base URL

https://api.bring.com

Usage	Method	Endpoint
Get all registered customer subscriptions for the user	GET	`/event-cast/api/v1/customer/webhooks`
Register a webhook on customer number	POST	`/event-cast/api/v1/customer/webhooks`
Renew an existing customer webhook subscription	POST	`/event-cast/api/v1/customer/webhooks/renew/{webhookSubscriptionId}`
Delete customer webhook subscription by id	DELETE	`/event-cast/api/v1/customer/webhooks/{webhookSubscriptionId}`
Get customer webhook subscription by id	GET	`/event-cast/api/v1/customer/webhooks/{webhookSubscriptionId}`
Get all registered tracking subscriptions	GET	`/event-cast/api/v1/webhooks`
Register a webhook on tracking number	POST	`/event-cast/api/v1/webhooks`
Delete tracking webhook subscription by id	DELETE	`/event-cast/api/v1/webhooks/{webhookSubscriptionId}`
Get tracking webhook subscription by id	GET	`/event-cast/api/v1/webhooks/{webhookSubscriptionId}`
Trigger a webhook test	POST	`/event-cast/api/v1/webhooks/{webhookSubscriptionId}/test`
Register webhook on multiple tracking numbers	POST	`/event-cast/batch/api/v1/webhooks`

OpenAPI document

https://api.bring.com/event-cast/api-docs

Get all registered customer subscriptions for the user

get

                  https://api.bring.com/event-cast/api/v1/customer/webhooks

Responses

200 Ok

array of objects

created

string <date-time>

customerNumber

string

eventSet

array of strings

: string

expiry

string <date-time>

id

string <uuid>

object

contentType

Required

string

Required

array of objects

key: string
value: string

webhookUrl

Required

string

404 No customer webhook subscriptions found

500 Something went wrong

reason Required: string
status Required: integer <int32>

Response examples

[
  {
    "created": "2024-05-22T07:42:13.86645",
    "customerNumber": "123456789",
    "eventSet": [
      "PRE_NOTIFIED",
      "DELIVERED",
      "DELIVERY_CHANGED"
    ],
    "expiry": "2025-05-22T07:42:13.86645",
    "id": "6e5ee30a-1419-4cdf-b63d-e75fbd83720f",
    "webhookConfiguration": {
      "contentType": "application/json",
      "headers": [
        {
          "key": "x-protection-header"
        },
        {
          "key": "x-required-company-header"
        }
      ],
      "webhookUrl": "https://example.com"
    }
  },
  {
    "created": "2024-07-21T07:42:13.86645",
    "customerNumber": "987654321",
    "eventSet": [
      "PRE_NOTIFIED",
      "DELIVERED"
    ],
    "expiry": "2025-07-21T07:42:13.86645",
    "id": "51b32bdf-b5f7-422a-a4da-f9966529c10s",
    "webhookConfiguration": {
      "contentType": "application/json",
      "headers": [
        {
          "key": "x-protection-header"
        },
        {
          "key": "x-required-company-header"
        }
      ],
      "webhookUrl": "https://example.com/other"
    }
  }
]

{
  "reason": "Something went wrong. Please try again later.",
  "status": 500
}

Register a webhook on customer number

post

                  https://api.bring.com/event-cast/api/v1/customer/webhooks

Register a webhook on customer to get notified about events on every consignment & parcel sent by customer. Use the MyBring customer number upon registration.

Note: Webhooks on customers are active for 1 year (365 days), unless deleted by the user. The subscription can be renewed by calling the /renew/{webhookSubscriptionId} endpoint.

Request

customerNumber

Required

string

eventSet

Required

array of strings

: string

Required

object

contentType

Required

string

Required

array of objects

key: string
value: string

webhookUrl

Required

string

Responses

201 Created

created

Required

string <date-time>

customerNumber

Required

string

eventSet

Required

array of strings

: string

expiry

Required

string <date-time>

id

Required

string <uuid>

Required

object

contentType

Required

string

Required

array of objects

key: string
value: string

webhookUrl

Required

string

400 Error creating webhook

reason Required: string
status Required: integer <int32>

401 Unauthorized to register webhook on customer number

reason Required: string
status Required: integer <int32>

500 Something went wrong

reason Required: string
status Required: integer <int32>

Request examples

{
  "customerNumber": "123456789",
  "eventSet": [
    "DELIVERED",
    "DELIVERY_CHANGED",
    "PRE_NOTIFIED"
  ],
  "webhookConfiguration": {
    "contentType": "application/json",
    "headers": [
      {
        "key": "x-protection-header",
        "value": "12345-67890"
      },
      {
        "key": "x-required-company-header",
        "value": "company@identification"
      }
    ],
    "webhookUrl": "https://example.com"
  }
}

Response examples

{
  "created": "2024-05-22T07:42:13.86645",
  "customerNumber": "123456789",
  "eventSet": [
    "DELIVERED",
    "DELIVERY_CHANGED",
    "PRE_NOTIFIED"
  ],
  "expiry": "2025-05-22T07:42:13.86645",
  "id": "6e5ee30a-1419-4cdf-b63d-e75fbd83720f",
  "webhookConfiguration": {
    "contentType": "application/json",
    "headers": [
      {
        "key": "x-protection-header"
      },
      {
        "key": "x-required-company-header"
      }
    ],
    "webhookUrl": "https://example.com"
  }
}

{
  "reason": "Request failed",
  "status": "400",
  "uuid": "023036"
}

{
  "reason": "User does not have access rights on customer number",
  "status": 401
}

{
  "reason": "Something went wrong. Please try again later.",
  "status": 500
}

Renew an existing customer webhook subscription

post

                  https://api.bring.com/event-cast/api/v1/customer/webhooks/renew/{webhookSubscriptionId}

Extend the expiry date of an existing customer webhook subscription. Upon renewal, the expiry date will be set to one year (365 days) from the time of the request.

Request

path parameters

webhookSubscriptionId

Required

Type: string

Responses

200 Ok

created

Required

string <date-time>

customerNumber

Required

string

eventSet

Required

array of strings

: string

expiry

Required

string <date-time>

id

Required

string <uuid>

Required

object

contentType

Required

string

Required

array of objects

key: string
value: string

webhookUrl

Required

string

404 No customer webhook subscription found

reason Required: string
status Required: integer <int32>

500 Something went wrong

reason Required: string
status Required: integer <int32>

Response examples

{
  "created": "2024-05-22T07:42:13.86645",
  "customerNumber": "123456789",
  "eventSet": [
    "DELIVERED",
    "DELIVERY_CHANGED",
    "PRE_NOTIFIED"
  ],
  "expiry": "2025-05-22T07:42:13.86645",
  "id": "6e5ee30a-1419-4cdf-b63d-e75fbd83720f",
  "webhookConfiguration": {
    "contentType": "application/json",
    "headers": [
      {
        "key": "x-protection-header"
      },
      {
        "key": "x-required-company-header"
      }
    ],
    "webhookUrl": "https://example.com"
  }
}

{
  "reason": "No Customer Subscription found",
  "status": 404
}

{
  "reason": "Something went wrong. Please try again later.",
  "status": 500
}

Delete customer webhook subscription by id

delete

                  https://api.bring.com/event-cast/api/v1/customer/webhooks/{webhookSubscriptionId}

Request

path parameters

webhookSubscriptionId

Required

Type: string

Responses

204 No content

404 No customer webhook subscription found

500 Something went wrong

reason Required: string
status Required: integer <int32>

Get customer webhook subscription by id

get

                  https://api.bring.com/event-cast/api/v1/customer/webhooks/{webhookSubscriptionId}

Request

path parameters

webhookSubscriptionId

Required

Type: string

Responses

200 Ok

created

Required

string <date-time>

customerNumber

Required

string

eventSet

Required

array of strings

: string

expiry

Required

string <date-time>

id

Required

string <uuid>

Required

object

contentType

Required

string

Required

array of objects

key: string
value: string

webhookUrl

Required

string

404 No customer webhook subscription found

reason Required: string
status Required: integer <int32>

500 Something went wrong

reason Required: string
status Required: integer <int32>

Response examples

{
  "created": "2024-05-22T07:42:13.86645",
  "customerNumber": "123456789",
  "eventSet": [
    "DELIVERED",
    "DELIVERY_CHANGED",
    "PRE_NOTIFIED"
  ],
  "expiry": "2025-05-22T07:42:13.86645",
  "id": "6e5ee30a-1419-4cdf-b63d-e75fbd83720f",
  "webhookConfiguration": {
    "contentType": "application/json",
    "headers": [
      {
        "key": "x-protection-header"
      },
      {
        "key": "x-required-company-header"
      }
    ],
    "webhookUrl": "https://example.com"
  }
}

{
  "reason": "No Customer Subscription found",
  "status": 404
}

{
  "reason": "Something went wrong. Please try again later.",
  "status": 500
}

Get all registered tracking subscriptions

get

                  https://api.bring.com/event-cast/api/v1/webhooks

Responses

200 OK

400 Authentication failed. Please set the mybring API login headers (X-MyBring-API-Uid and X-MyBring-API-Key) to a valid combination.

500 Internal Server Error

Response examples

Successful response

[
  {
    "authenticator": "abcThis-isAn-Authentication-Combination-123ABC",
    "configuration": {
      "content_type": "application/json",
      "headers": [
        {
          "key": "x-protection-header"
        },
        {
          "key": "x-required-company-header"
        }
      ],
      "url": "http://localhost:8888/some/random/location"
    },
    "created": "2022-10-26T11:49:30+0000",
    "event_groups": [
      "DELIVERED"
    ],
    "expiry": "2022-11-25T11:49:30+0000",
    "id": "e9e1d236-15a4-421e-a6d3-05a60901ef34",
    "trackingId": "TESTORDERHOMEDELIVERYDK"
  },
  {
    "authenticator": "abcThis-isAn-Authentication-Combination-123ABC",
    "configuration": {
      "content_type": "application/json",
      "headers": [
        {
          "key": "x-protection-header"
        },
        {
          "key": "x-required-company-header"
        }
      ],
      "url": "http://localhost:8888/some/random/location"
    },
    "created": "2022-10-26T11:49:30+0000",
    "event_groups": [
      "DELIVERED"
    ],
    "expiry": "2022-11-25T11:49:30+0000",
    "id": "712dbcdb-2a98-4dda-9452-55150094e995",
    "trackingId": "TESTSWIPBOXBANKIDVERIFICATIONSE"
  }
]

Register a webhook on tracking number

post

                  https://api.bring.com/event-cast/api/v1/webhooks

Create a new subscription for a Webhook. Webhooks lives for up to 30 days, or until the entity subscribed for is marked as Delivered by Bring.

Note: Subscription is allowed only on package and shipment numbers, and not on reference number or label free code.

Request

authenticator

stringMax length: 40

object

content_type

stringMax length: 40

array of objects

key: string
value: string

url

stringMax length: 250

created

string <date-time>

event_groups

array of strings

: string

expiry

string <date-time>

id

string

trackingId

string

Responses

201 Created

authenticator

stringMax length: 40

object

content_type

stringMax length: 40

array of objects

key: string
value: string

url

stringMax length: 250

created

string <date-time>

event_groups

array of strings

: string

expiry

string <date-time>

id

string

trackingId

string

400 Error creating webhook

reason: string
status: string
uuid: string

409 Conflict

reason: string
status: string
uuid: string

500 Internal Server Error

Request examples

Create a webhook

{
  "configuration": {
    "content_type": "application/json",
    "headers": [
      {
        "key": "x-protection-header",
        "value": "12345-67890"
      },
      {
        "key": "x-required-company-header",
        "value": "company@identification"
      }
    ],
    "url": "http://localhost:8888/your/endpoint/"
  },
  "event_groups": [
    "DELIVERED",
    "IN_TRANSIT",
    "DEVIATION"
  ],
  "trackingId": "TESTSWIPBOXBANKIDVERIFICATIONSE"
}

Response examples

Success response

{
  "authenticator": "abcThis-isAn-Authentication-Combination-123ABC",
  "configuration": {
    "content_type": "application/json",
    "headers": [
      {
        "key": "x-protection-header"
      },
      {
        "key": "x-required-company-header"
      }
    ],
    "url": "http://localhost:8888/some/random/location"
  },
  "created": "2022-10-24T07:40:31+0000",
  "event_groups": [
    "DELIVERED",
    "IN_TRANSIT",
    "DEVIATION"
  ],
  "expiry": "2022-11-23T07:40:31+0000",
  "id": "c21b8754-271b-47e9-afd2-31e1b3804c45",
  "trackingId": "TESTSWIPBOXBANKIDVERIFICATIONSE"
}

Error response

{
  "reason": "Request failed",
  "status": "400",
  "uuid": "023036"
}

Conflict response

{
  "reason": "Webhook Subscription already exists.",
  "status": "409",
  "uuid": "023036"
}

Delete tracking webhook subscription by id

delete

                  https://api.bring.com/event-cast/api/v1/webhooks/{webhookSubscriptionId}

Request

path parameters

webhookSubscriptionId

Required

Type: string

query parameters

includeWebhook

Description: Include the deleted webhook in the response
Type: boolean
Default: false

Responses

204 No Content

: string

400 Authentication failed. Please set the mybring API login headers (X-MyBring-API-Uid and X-MyBring-API-Key) to a valid combination.

: string

404 Webhook not found

: string

500 Internal Server Error

Get tracking webhook subscription by id

get

                  https://api.bring.com/event-cast/api/v1/webhooks/{webhookSubscriptionId}

Request

path parameters

webhookSubscriptionId

Required

Type: string

Responses

200 OK

404 Webhook not found

authenticator

stringMax length: 40

object

content_type

stringMax length: 40

array of objects

key: string
value: string

url

stringMax length: 250

created

string <date-time>

event_groups

array of strings

: string

expiry

string <date-time>

id

string

trackingId

string

500 Internal Server Error

Response examples

Successful response

[
  {
    "authenticator": "abcThis-isAn-Authentication-Combination-123ABC",
    "configuration": {
      "content_type": "application/json",
      "headers": [
        {
          "key": "x-protection-header"
        },
        {
          "key": "x-required-company-header"
        }
      ],
      "url": "http://localhost:8888/some/random/location"
    },
    "created": "2022-10-24T10:53:26+0000",
    "event_groups": [
      "DELIVERED"
    ],
    "expiry": "2022-11-23T10:53:26+0000",
    "id": "fb50f0b7-9cb4-4279-99e8-67f2d7bc24f9",
    "trackingId": "TESTORDERHOMEDELIVERYDK"
  }
]

Trigger a webhook test

post

                  https://api.bring.com/event-cast/api/v1/webhooks/{webhookSubscriptionId}/test

Use this endpoint to test your webhook configuration by sending a dummy request to the specified webhook.
It supports both tracking and customer number based webhooks.

Note: ⚠️ This endpoint will return a 200 OK status if the test operation itself is successful, regardless of the webhook's response.
The response body will contain the actual result of the test. Please review the response to understand the test outcome.

Request

path parameters

webhookSubscriptionId

Required

Type: string

Responses

200 The test was processed successfully. Check the response for details.

: string

400 Authentication failed. Please set the mybring API login headers (X-MyBring-API-Uid and X-MyBring-API-Key) to a valid combination.

: string

404 Webhook not found

: string

Register webhook on multiple tracking numbers

post

                  https://api.bring.com/event-cast/batch/api/v1/webhooks

Create a range of new Webhooks based on a list of any parcel or shipment. Webhooks lives for up to 30 days, or until the entity subscribed for is marked as Delivered by Bring.

Note: Subscription is allowed only on package and shipment numbers, and not on reference number or label free code.

Request

authenticator

stringMax length: 40

object

content_type

stringMax length: 40

array of objects

key: string
value: string

url

stringMax length: 250

created

string <date-time>

event_groups

array of strings

: string

expiry

string <date-time>

trackingIds

array of strings

: string

Responses

200 Created

: string

400 Authentication failed. Please set the mybring API login headers (X-MyBring-API-Uid and X-MyBring-API-Key) to a valid combination.

409 Conflict

500 Internal Server Error

Request examples

Create multiple webhook

{
  "configuration": {
    "content_type": "application/json",
    "headers": [
      {
        "key": "x-protection-header",
        "value": "12345-67890"
      },
      {
        "key": "x-required-company-header",
        "value": "company@identification"
      }
    ],
    "url": "http://localhost:8888/some/random/location"
  },
  "event_groups": [
    "DELIVERED"
  ],
  "trackingIds": [
    "TESTSWIPBOXBANKIDVERIFICATIONSE",
    "TESTORDERHOMEDELIVERYDK"
  ]
}

Response examples

Success response

{
  "authenticator": "abcThis-isAn-Authentication-Combination-123ABC",
  "configuration": {
    "content_type": "application/json",
    "headers": [
      {
        "key": "x-protection-header"
      },
      {
        "key": "x-required-company-header"
      }
    ],
    "url": "http://localhost:8888/some/random/location"
  },
  "created": "2022-10-24T07:40:31+0000",
  "event_groups": [
    "DELIVERED",
    "IN_TRANSIT",
    "DEVIATION"
  ],
  "expiry": "2022-11-23T07:40:31+0000",
  "id": "c21b8754-271b-47e9-afd2-31e1b3804c45",
  "trackingId": "TESTSWIPBOXBANKIDVERIFICATIONSE"
}

Conflict response

{
  "reason": "Webhook Subscription already exists.",
  "status": "409",
  "uuid": "023036"
}

Event Cast API

19 June 2024: Event Cast API - Subscription on customer numbers

Events

Callbacks

Information Bring will provide in the request

Example callback from Bring to your endpoint

Retries

Endpoints

OpenAPI document

Get all registered customer subscriptions for the user

Responses

Schema

Schema

Response examples

Register a webhook on customer number

Request

Body schema

Responses

Schema

Schema

Schema

Schema

Request examples

Response examples

Renew an existing customer webhook subscription

Request

path parameters

Responses

Schema

Schema

Schema

Response examples

Delete customer webhook subscription by id

Request

path parameters

Responses

Schema

Get customer webhook subscription by id

Request

path parameters

Responses

Schema

Schema

Schema

Response examples

Get all registered tracking subscriptions

Responses

Response examples

Successful response

Register a webhook on tracking number

Request

Body schema

Responses

Schema

Schema

Schema

Request examples

Create a webhook

Response examples

Success response

Error response

Conflict response

Delete tracking webhook subscription by id

Request

path parameters

query parameters

Responses

Schema

Schema

Schema

Get tracking webhook subscription by id

Request

path parameters

Responses

Schema

Response examples

Successful response

Trigger a webhook test

Request

path parameters