Skip to main content

Event Cast API

The Event Cast API can be used to subscribe to tracking events for a given shipment using webhooks. Event notifications are automatically pushed to the subscriber as they happen, which makes it unnecessary to repeatedly poll statuses calling the Tracking API. You define an endpoint that accepts HTTP POST, and whenever an event is registered for a subscribed shipment, we send it to the 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

The API allows a maximum of 50 concurrent requests per user. The maximum amount of shipments that can be batch created is limited to 100 per request. The test endpoint allows a maximum of 10 concurrent requests per user.

Formats

REST XML/JSON over HTTP.

Events

When registering for a Webhook you can choose between a range of different event groups that you can subscribe for. It is recommended to limit the amount of events to subscribe for. Bring will send an event on each of the events occurred which in result may send quite a few HTTP-requests to your server. So, as a good practise, keep the list of event groups as small as possible.

Each of the event groups corresponds to a certain set of actions that can happen to the package/shipment you subscribe for. For instance, if you subscribe to DELIVERED, all internal Bring-events will trigger a request to your defined callback URL.

Event groups

Default set of subscribable event groups. Notice that this list is subject for change.

Event Description
ATTEMPTED_DELIVERY The 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 The parcel 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 notifications and action notification 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 The package is on its way back to the sender.
TRANSPORT_TO_RECIPIENT Package has been loaded for delivery to the recipient.
TERMINAL The package is now registered/arrived at inbound/outbound storage terminal

There is also a specific set of events that will be sent if something deviates from the normal event flow:

Event Description
NOT_REGISTERED Webhook not registered. This might be due to the parcel-/shipment-number not being found with Bring’ systems and can trigger after up to two - 2 - days
EXPIRED Webhook expired

Subscribing to multiple event groups

The Webhook API supports the possibility to subscribe to multiple event groups at the same time. Doing so requires that groups are separated with comma and is defined as an array. Example:

['IN_TRANSIT', 'NOTIFICATION_SENT', 'TERMINAL', .., ..]

Need more examples? See the “Create Webhook” section below.

Receiving 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. Additionally, to minimize risk, you should also provide HTTPS-enabled endpoints and use some kind of authentication mechanism. For HTTPS, please do not use self-signed certificates, as requests may fail from Bring’ side and you’ll receive no requests.

If you need a simple authentication whilst receiving requests from Bring, we recommend utilizing 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"

Payload

Payload delivery headers

HTTP POST payloads that are delivered to your Webhook’s configured URL endpoint contains 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 whilst contacting Bring on error cases
X-bring-Version Indicates the version of application
<your headers> Any headers that were specified in the Webhook configuration will also be appended

Example

Requests issued from Bring to your endpoint will look similar to this:

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

Q & A

Can I have multiple Webhooks for the same parcel?
You can register for multiple Webhooks on the same parcel/shipment, as long as the event groups are different for each registration.

How many active Webhooks can I have simultaneously?
Currently there is no limitation.

Is the expiration duration configurable?
No.

Can I get a history of events that were sent for a subscription?
Not in this version. It may be available in the future. Please note that you may use the Tracking API if you’d like the entire list of events that has happened for a lifecycle related to a shipment.

Will I be able to see my previous/expired Webhooks (active and inactive)?
No.

What happens if our endpoint is down and a callback is being sent?
We’ll try issuing a request to your defined endpoint up to three - 3 - times with a delay on 30 minutes for the two first, then wait an hour for the last retry. After this, callbacks will not be retried.

Do you support wildcard events/event groups (e.g * or ALL)?
No.

Do you support modifying existing active webhooks?
No.

My shipment is not yet registered with Bring, will registering for Webhook work related to that tracking number?
Yes.

When you subscribe for a parcel that does not yet exist in Bring’ systems, a retry mechanism will try for up to two - 2 - days to ensure that the Webhook will be registered when the parcel is found internally. Eventually, if the package was not found with Bring within this timeframe - a notification will be sent on the callback URL configured for that Webhook which notifies this.

Note: Retry-timing is non-configurable.

Endpoints

Base URL
https://api.bring.com
Usage Method Endpoint
Get all webhooks GET /event-cast/api/v1/webhooks
Create a webhook POST /event-cast/api/v1/webhooks
Delete a webhook subscription DELETE /event-cast/api/v1/webhooks/{webhookSubscriptionId}
Get a single webhook subscription by id GET /event-cast/api/v1/webhooks/{webhookSubscriptionId}
Test to trigger a webhook POST /event-cast/api/v1/webhooks/{webhookSubscriptionId}/test
Create multiple webhooks POST /event-cast/batch/api/v1/webhooks

Get all webhooks

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

Create a webhook

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

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 a webhook subscription

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 a single 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

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

Test to trigger a webhook

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

Calling this endpoint will trigger a Webhook by sending a dummy request to the registered Webhook. Note: ⚠️ This endpoint will return 200 ok regardless of what your webhook returns, as long as the test operation itself was successful. The body will contain the actual result of the test. Please study the response to see the result of the test.

Request

path parameters

webhookSubscriptionId
Required
Type
string

Responses

200 Test processed OK, check response for result

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

Create multiple webhooks

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