Skip to main content

Event Cast API

: Important Update! New TLS certificates on api.bring.com 27th of October 2025

Migration from Buypass to Let’s Encrypt TLS Certificates As of 15 September 2025, Buypass has stopped allowing registration of new ACME Account and will stop generating/renewing TLS certificates from 15th October 2025. To ensure continuity, we are migrating all TLS certificates from Buypass to Let´s Encrypt.

As part of this activity:

  • Old Buypass certificates will be removed
  • New Let´s Encrypt certificates will be created

Impact to Customers:

  • If your application does not pin the certificate, no action is required and there will be zero impact.
  • If your application does pin the certificate, you will need to download the new Let´s Encrypt certificate and update your application configuration accordingly.

We recommend reviewing your applications to check whether certificate pinning is in place and preparing for updates if needed.

For more queries, contact integrasjon.norge@bring.com (Norway) or edi@bring.com (outside Norway).

: 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:

  1. Customer Number Subscription: Event notifications will be sent for all shipments belonging to the subscribed customer number.
  2. 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
Get all webhooks on customer numbers a user has access to GET /event-cast/api/v1/customer/webhooks/all
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

Get all registered customer subscriptions for the user

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

Responses

200 Ok

Schema

Media type: application/json

array of objects
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
Required
string
value
string
webhookUrl
Required
string
404 No customer webhook subscriptions found
500 Something went wrong

Schema

Media type: application/json

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"
    }
  }
]

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

Body schema

Media type: application/json

customerNumber
Required
string
eventSet
Required
array of strings
string
Required
object
contentType
Required
string
Required
array of objects
key
Required
string
value
string
webhookUrl
Required
string

Responses

201 Created

Schema

Media type: application/json

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
Required
string
value
string
webhookUrl
Required
string
400 Error creating webhook

Schema

Media type: application/json

reason
Required
string
status
Required
integer <int32>
401 Unauthorized to register webhook on customer number

Schema

Media type: application/json

reason
Required
string
status
Required
integer <int32>
500 Something went wrong

Schema

Media type: application/json

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"
  }
}

Get all webhooks on customer numbers a user has access to

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

Returns all registered webhooks on the customer numbers that is connected to the user accessing the endpoint.

Responses

200 Successfully returned a list of webhooks

Schema

Media type: application/json

created
Required
string <date-time>
createdBy
Required
string
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
Required
string
value
string
webhookUrl
Required
string
401 Unauthorized: Either the user is not authorized to access the customer number, or not authorized to access the API.

Schema

Media type: application/json

Schema (oneOf)
reason
Required
string
status
Required
integer <int32>
clientMessage
Required
string
message
Required
string
severity
Required
string
Enum
ERROR
WARNING
INFO
shouldLog
Required
boolean
status
Required
string
Enum
100 CONTINUE
101 SWITCHING_PROTOCOLS
102 PROCESSING
103 EARLY_HINTS
103 CHECKPOINT
200 OK
201 CREATED
202 ACCEPTED
203 NON_AUTHORITATIVE_INFORMATION
204 NO_CONTENT
205 RESET_CONTENT
206 PARTIAL_CONTENT
207 MULTI_STATUS
208 ALREADY_REPORTED
226 IM_USED
300 MULTIPLE_CHOICES
301 MOVED_PERMANENTLY
302 FOUND
302 MOVED_TEMPORARILY
303 SEE_OTHER
304 NOT_MODIFIED
305 USE_PROXY
307 TEMPORARY_REDIRECT
308 PERMANENT_REDIRECT
400 BAD_REQUEST
401 UNAUTHORIZED
402 PAYMENT_REQUIRED
403 FORBIDDEN
404 NOT_FOUND
405 METHOD_NOT_ALLOWED
406 NOT_ACCEPTABLE
407 PROXY_AUTHENTICATION_REQUIRED
408 REQUEST_TIMEOUT
409 CONFLICT
410 GONE
411 LENGTH_REQUIRED
412 PRECONDITION_FAILED
413 PAYLOAD_TOO_LARGE
413 REQUEST_ENTITY_TOO_LARGE
414 URI_TOO_LONG
414 REQUEST_URI_TOO_LONG
415 UNSUPPORTED_MEDIA_TYPE
416 REQUESTED_RANGE_NOT_SATISFIABLE
417 EXPECTATION_FAILED
418 I_AM_A_TEAPOT
419 INSUFFICIENT_SPACE_ON_RESOURCE
420 METHOD_FAILURE
421 DESTINATION_LOCKED
422 UNPROCESSABLE_ENTITY
423 LOCKED
424 FAILED_DEPENDENCY
425 TOO_EARLY
426 UPGRADE_REQUIRED
428 PRECONDITION_REQUIRED
429 TOO_MANY_REQUESTS
431 REQUEST_HEADER_FIELDS_TOO_LARGE
451 UNAVAILABLE_FOR_LEGAL_REASONS
500 INTERNAL_SERVER_ERROR
501 NOT_IMPLEMENTED
502 BAD_GATEWAY
503 SERVICE_UNAVAILABLE
504 GATEWAY_TIMEOUT
505 HTTP_VERSION_NOT_SUPPORTED
506 VARIANT_ALSO_NEGOTIATES
507 INSUFFICIENT_STORAGE
508 LOOP_DETECTED
509 BANDWIDTH_LIMIT_EXCEEDED
510 NOT_EXTENDED
511 NETWORK_AUTHENTICATION_REQUIRED
reason
Required
string
status
Required
integer <int32>
clientMessage
Required
string
message
Required
string
severity
Required
string
Enum
ERROR
WARNING
INFO
shouldLog
Required
boolean
status
Required
string
Enum
100 CONTINUE
101 SWITCHING_PROTOCOLS
102 PROCESSING
103 EARLY_HINTS
103 CHECKPOINT
200 OK
201 CREATED
202 ACCEPTED
203 NON_AUTHORITATIVE_INFORMATION
204 NO_CONTENT
205 RESET_CONTENT
206 PARTIAL_CONTENT
207 MULTI_STATUS
208 ALREADY_REPORTED
226 IM_USED
300 MULTIPLE_CHOICES
301 MOVED_PERMANENTLY
302 FOUND
302 MOVED_TEMPORARILY
303 SEE_OTHER
304 NOT_MODIFIED
305 USE_PROXY
307 TEMPORARY_REDIRECT
308 PERMANENT_REDIRECT
400 BAD_REQUEST
401 UNAUTHORIZED
402 PAYMENT_REQUIRED
403 FORBIDDEN
404 NOT_FOUND
405 METHOD_NOT_ALLOWED
406 NOT_ACCEPTABLE
407 PROXY_AUTHENTICATION_REQUIRED
408 REQUEST_TIMEOUT
409 CONFLICT
410 GONE
411 LENGTH_REQUIRED
412 PRECONDITION_FAILED
413 PAYLOAD_TOO_LARGE
413 REQUEST_ENTITY_TOO_LARGE
414 URI_TOO_LONG
414 REQUEST_URI_TOO_LONG
415 UNSUPPORTED_MEDIA_TYPE
416 REQUESTED_RANGE_NOT_SATISFIABLE
417 EXPECTATION_FAILED
418 I_AM_A_TEAPOT
419 INSUFFICIENT_SPACE_ON_RESOURCE
420 METHOD_FAILURE
421 DESTINATION_LOCKED
422 UNPROCESSABLE_ENTITY
423 LOCKED
424 FAILED_DEPENDENCY
425 TOO_EARLY
426 UPGRADE_REQUIRED
428 PRECONDITION_REQUIRED
429 TOO_MANY_REQUESTS
431 REQUEST_HEADER_FIELDS_TOO_LARGE
451 UNAVAILABLE_FOR_LEGAL_REASONS
500 INTERNAL_SERVER_ERROR
501 NOT_IMPLEMENTED
502 BAD_GATEWAY
503 SERVICE_UNAVAILABLE
504 GATEWAY_TIMEOUT
505 HTTP_VERSION_NOT_SUPPORTED
506 VARIANT_ALSO_NEGOTIATES
507 INSUFFICIENT_STORAGE
508 LOOP_DETECTED
509 BANDWIDTH_LIMIT_EXCEEDED
510 NOT_EXTENDED
511 NETWORK_AUTHENTICATION_REQUIRED
404 No webhooks found on customer number

Schema

Media type: application/json

clientMessage
Required
string
message
Required
string
severity
Required
string
Enum
ERROR
WARNING
INFO
shouldLog
Required
boolean
status
Required
string
Enum
100 CONTINUE
101 SWITCHING_PROTOCOLS
102 PROCESSING
103 EARLY_HINTS
103 CHECKPOINT
200 OK
201 CREATED
202 ACCEPTED
203 NON_AUTHORITATIVE_INFORMATION
204 NO_CONTENT
205 RESET_CONTENT
206 PARTIAL_CONTENT
207 MULTI_STATUS
208 ALREADY_REPORTED
226 IM_USED
300 MULTIPLE_CHOICES
301 MOVED_PERMANENTLY
302 FOUND
302 MOVED_TEMPORARILY
303 SEE_OTHER
304 NOT_MODIFIED
305 USE_PROXY
307 TEMPORARY_REDIRECT
308 PERMANENT_REDIRECT
400 BAD_REQUEST
401 UNAUTHORIZED
402 PAYMENT_REQUIRED
403 FORBIDDEN
404 NOT_FOUND
405 METHOD_NOT_ALLOWED
406 NOT_ACCEPTABLE
407 PROXY_AUTHENTICATION_REQUIRED
408 REQUEST_TIMEOUT
409 CONFLICT
410 GONE
411 LENGTH_REQUIRED
412 PRECONDITION_FAILED
413 PAYLOAD_TOO_LARGE
413 REQUEST_ENTITY_TOO_LARGE
414 URI_TOO_LONG
414 REQUEST_URI_TOO_LONG
415 UNSUPPORTED_MEDIA_TYPE
416 REQUESTED_RANGE_NOT_SATISFIABLE
417 EXPECTATION_FAILED
418 I_AM_A_TEAPOT
419 INSUFFICIENT_SPACE_ON_RESOURCE
420 METHOD_FAILURE
421 DESTINATION_LOCKED
422 UNPROCESSABLE_ENTITY
423 LOCKED
424 FAILED_DEPENDENCY
425 TOO_EARLY
426 UPGRADE_REQUIRED
428 PRECONDITION_REQUIRED
429 TOO_MANY_REQUESTS
431 REQUEST_HEADER_FIELDS_TOO_LARGE
451 UNAVAILABLE_FOR_LEGAL_REASONS
500 INTERNAL_SERVER_ERROR
501 NOT_IMPLEMENTED
502 BAD_GATEWAY
503 SERVICE_UNAVAILABLE
504 GATEWAY_TIMEOUT
505 HTTP_VERSION_NOT_SUPPORTED
506 VARIANT_ALSO_NEGOTIATES
507 INSUFFICIENT_STORAGE
508 LOOP_DETECTED
509 BANDWIDTH_LIMIT_EXCEEDED
510 NOT_EXTENDED
511 NETWORK_AUTHENTICATION_REQUIRED
500 Something went wrong

Schema

Media type: application/json

Schema (oneOf)
reason
Required
string
status
Required
integer <int32>
clientMessage
Required
string
message
Required
string
severity
Required
string
Enum
ERROR
WARNING
INFO
shouldLog
Required
boolean
status
Required
string
Enum
100 CONTINUE
101 SWITCHING_PROTOCOLS
102 PROCESSING
103 EARLY_HINTS
103 CHECKPOINT
200 OK
201 CREATED
202 ACCEPTED
203 NON_AUTHORITATIVE_INFORMATION
204 NO_CONTENT
205 RESET_CONTENT
206 PARTIAL_CONTENT
207 MULTI_STATUS
208 ALREADY_REPORTED
226 IM_USED
300 MULTIPLE_CHOICES
301 MOVED_PERMANENTLY
302 FOUND
302 MOVED_TEMPORARILY
303 SEE_OTHER
304 NOT_MODIFIED
305 USE_PROXY
307 TEMPORARY_REDIRECT
308 PERMANENT_REDIRECT
400 BAD_REQUEST
401 UNAUTHORIZED
402 PAYMENT_REQUIRED
403 FORBIDDEN
404 NOT_FOUND
405 METHOD_NOT_ALLOWED
406 NOT_ACCEPTABLE
407 PROXY_AUTHENTICATION_REQUIRED
408 REQUEST_TIMEOUT
409 CONFLICT
410 GONE
411 LENGTH_REQUIRED
412 PRECONDITION_FAILED
413 PAYLOAD_TOO_LARGE
413 REQUEST_ENTITY_TOO_LARGE
414 URI_TOO_LONG
414 REQUEST_URI_TOO_LONG
415 UNSUPPORTED_MEDIA_TYPE
416 REQUESTED_RANGE_NOT_SATISFIABLE
417 EXPECTATION_FAILED
418 I_AM_A_TEAPOT
419 INSUFFICIENT_SPACE_ON_RESOURCE
420 METHOD_FAILURE
421 DESTINATION_LOCKED
422 UNPROCESSABLE_ENTITY
423 LOCKED
424 FAILED_DEPENDENCY
425 TOO_EARLY
426 UPGRADE_REQUIRED
428 PRECONDITION_REQUIRED
429 TOO_MANY_REQUESTS
431 REQUEST_HEADER_FIELDS_TOO_LARGE
451 UNAVAILABLE_FOR_LEGAL_REASONS
500 INTERNAL_SERVER_ERROR
501 NOT_IMPLEMENTED
502 BAD_GATEWAY
503 SERVICE_UNAVAILABLE
504 GATEWAY_TIMEOUT
505 HTTP_VERSION_NOT_SUPPORTED
506 VARIANT_ALSO_NEGOTIATES
507 INSUFFICIENT_STORAGE
508 LOOP_DETECTED
509 BANDWIDTH_LIMIT_EXCEEDED
510 NOT_EXTENDED
511 NETWORK_AUTHENTICATION_REQUIRED
userId
Required
string
reason
Required
string
status
Required
integer <int32>
localizedMessage
string
message
string
stackTrace
array of objects
object
classLoaderName
string
className
string
fileName
string
lineNumber
integer <int32>
methodName
string
moduleName
string
moduleVersion
string
nativeMethod
boolean
clientMessage
Required
string
message
Required
string
severity
Required
string
Enum
ERROR
WARNING
INFO
shouldLog
Required
boolean
status
Required
string
Enum
100 CONTINUE
101 SWITCHING_PROTOCOLS
102 PROCESSING
103 EARLY_HINTS
103 CHECKPOINT
200 OK
201 CREATED
202 ACCEPTED
203 NON_AUTHORITATIVE_INFORMATION
204 NO_CONTENT
205 RESET_CONTENT
206 PARTIAL_CONTENT
207 MULTI_STATUS
208 ALREADY_REPORTED
226 IM_USED
300 MULTIPLE_CHOICES
301 MOVED_PERMANENTLY
302 FOUND
302 MOVED_TEMPORARILY
303 SEE_OTHER
304 NOT_MODIFIED
305 USE_PROXY
307 TEMPORARY_REDIRECT
308 PERMANENT_REDIRECT
400 BAD_REQUEST
401 UNAUTHORIZED
402 PAYMENT_REQUIRED
403 FORBIDDEN
404 NOT_FOUND
405 METHOD_NOT_ALLOWED
406 NOT_ACCEPTABLE
407 PROXY_AUTHENTICATION_REQUIRED
408 REQUEST_TIMEOUT
409 CONFLICT
410 GONE
411 LENGTH_REQUIRED
412 PRECONDITION_FAILED
413 PAYLOAD_TOO_LARGE
413 REQUEST_ENTITY_TOO_LARGE
414 URI_TOO_LONG
414 REQUEST_URI_TOO_LONG
415 UNSUPPORTED_MEDIA_TYPE
416 REQUESTED_RANGE_NOT_SATISFIABLE
417 EXPECTATION_FAILED
418 I_AM_A_TEAPOT
419 INSUFFICIENT_SPACE_ON_RESOURCE
420 METHOD_FAILURE
421 DESTINATION_LOCKED
422 UNPROCESSABLE_ENTITY
423 LOCKED
424 FAILED_DEPENDENCY
425 TOO_EARLY
426 UPGRADE_REQUIRED
428 PRECONDITION_REQUIRED
429 TOO_MANY_REQUESTS
431 REQUEST_HEADER_FIELDS_TOO_LARGE
451 UNAVAILABLE_FOR_LEGAL_REASONS
500 INTERNAL_SERVER_ERROR
501 NOT_IMPLEMENTED
502 BAD_GATEWAY
503 SERVICE_UNAVAILABLE
504 GATEWAY_TIMEOUT
505 HTTP_VERSION_NOT_SUPPORTED
506 VARIANT_ALSO_NEGOTIATES
507 INSUFFICIENT_STORAGE
508 LOOP_DETECTED
509 BANDWIDTH_LIMIT_EXCEEDED
510 NOT_EXTENDED
511 NETWORK_AUTHENTICATION_REQUIRED
userId
Required
string

Response examples

[
  {
    "created": "2025-06-23T10:50:28.329749",
    "createdBy": "employee-1@mailservice.com",
    "customerNumber": "example-customer-number",
    "eventSet": [
      "DELIVERED",
      "DELIVERED_SENDER",
      "DELIVERY_CANCELLED",
      "RETURN",
      "TERMINAL"
    ],
    "expiry": "2026-08-12T17:13:21.597011",
    "id": "example-id-1",
    "webhookConfiguration": {
      "contentType": "application/json",
      "headers": [
        {
          "key": "x-protection-header"
        },
        {
          "key": "x-required-company-header"
        }
      ],
      "webhookUrl": "example-webhook-url-1"
    }
  },
  {
    "created": "2025-09-09T11:20:33.864513",
    "createdBy": "employee-2@mailservice.com",
    "customerNumber": "example-customer-number",
    "eventSet": [
      "DELIVERED",
      "PRE_NOTIFIED"
    ],
    "expiry": "2026-09-09T11:20:33.864519",
    "id": "example-id-2",
    "webhookConfiguration": {
      "contentType": "application/json",
      "headers": [
        {
          "key": "x-protection-header"
        },
        {
          "key": "x-required-company-header"
        }
      ],
      "webhookUrl": "example-webhook-url-2"
    }
  },
  {
    "created": "2025-08-26T09:03:21.205615",
    "createdBy": "employee-1@mailservice.com",
    "customerNumber": "example-customer-number",
    "eventSet": [
      "DELIVERED",
      "DELIVERED_SENDER",
      "DELIVERY_CANCELLED",
      "DELIVERY_CHANGED",
      "IN_TRANSIT",
      "PRE_NOTIFIED",
      "READY_FOR_PICKUP"
    ],
    "expiry": "2026-08-26T09:03:21.214897",
    "id": "example-id-3",
    "webhookConfiguration": {
      "contentType": "application/json",
      "headers": [
        {
          "key": "x-protection-header"
        },
        {
          "key": "x-auth-key"
        }
      ],
      "webhookUrl": "example-webhook-url-3"
    }
  }
]

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

Schema

Media type: application/json

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
Required
string
value
string
webhookUrl
Required
string
404 No customer webhook subscription found

Schema

Media type: application/json

reason
Required
string
status
Required
integer <int32>
500 Something went wrong

Schema

Media type: application/json

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"
  }
}

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

Schema

Media type: application/json

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

Schema

Media type: application/json

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
Required
string
value
string
webhookUrl
Required
string
404 No customer webhook subscription found

Schema

Media type: application/json

reason
Required
string
status
Required
integer <int32>
500 Something went wrong

Schema

Media type: application/json

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"
  }
}

Get all registered tracking subscriptions

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

Responses

200 OK

Schema

Media type: application/json

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
array
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. A 409 Conflict response occurs when the same webhook details are submitted multiple times. To avoid this, ensure that the combination of shipment number, event groups, and webhook configuration in your request is unique.

Request

Body schema

Media type: application/json

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

Schema

Media type: application/json

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

Schema

Media type: application/json

reason
string
status
string
uuid
string
409 Conflict

Schema

Media type: application/json

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"
}

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

Schema

Media type: application/json

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

Schema

Media type: application/json

string
404 Webhook not found

Schema

Media type: application/json

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

Schema

Media type: application/json

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
404 Webhook not found

Schema

Media type: application/json

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.

Schema

Media type: text/plain

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

Schema

Media type: text/plain

string
404 Webhook not found

Schema

Media type: text/plain

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

Body schema

Media type: application/json

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

Schema

Media type: application/json

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"
}
comments powered by Disqus