Event Cast API

Introduction

The Tracking API provides the opportunity to track shipments by reference, package or shipment number. If you are interested in when a shipment is picket up by the recipient or some other event has happened, then it’s better to be told when something happens instead of polling the current status.

The Event Cast API makes you subscribe to such events using Webhooks.

Webohook Definition

A Webhook in web development is a method of augmenting or altering the behaviour of a web page, or web application, with custom callbacks. These callbacks may be maintained, modified, and managed by third-party users and developers who may not necessarily be affiliated with the originating website or application.

Webhooks in Bring

In the context of Bring, this means that whenever an event is registered in Bring for a subscribed parcel and/or shipment, we’ll send a HTTP POST to your callback URL that were defined during the Webhook registration.

Using Webhooks is quite simple, and allows for immediate feedback based on the event that occured for the subscribed entity. Additionally, it allows integrations of customers to become simpler, as no scheduled mechanism is required to be implemented. You basically just define an endpoint that accepts HTTP POST, and the event details will be sent there - quite amazing 🙌

Authentication

In order to use the API, you will need to register with Mybring and create an API key. Whenever issuing a request, the following headers is required to be present.

Header Example Comment Required
X-MyBring-API-Uid john.doe@example.com Mybring login ID
X-MyBring-API-Key 1234abc-abcd-1234-5678-abcd1234abcd Mybring login’s API key
X-Bring-Client-URL https://example.com/ A URL that sort of identifies you  

Note: See the getting started guide on authentication if you want to know more about how to get started with authentication for APIs in Mybring.

API limitations

There is some known/deliberate limitations for the API:

Resource Limitation description
All requests The Webhook API allows a maximum of 50 concurrent requests per user
Batch creation Whilst creating requests for Webhooks is a feature we encurage to use, its maximum amount of parcels and/or shipments is limited to 100 per request. If you have more than 100 at the time, split to mulitple requests using the batch-API
Webhook testing The /api/v1/Webhooks/{WebhookId}/test-api allows a maximum of 10 concurrent requests per user

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 subscribeable event groups. Notice that this list is subject for change.

Event Description
ARRIVED_DELIVERY Arrived Delivery point - This is when a container arrives at recipients address, and can start unloading.

ARRIVED_COLLECTION Arrived for collection at pickup point
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 canceled 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 has been returned to 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.

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.

Overview of endpoints

Base URL

https://api.bring.com/event-cast
Method Endpoint Usage
POST /api/v1/webhooks Register a new Webhook subscription for a parcel or shipment
POST /batch/api/v1/webhooks Register a new Webhook subscription for an array parcels and/or shipments
DELETE /api/v1/webhooks/{Webhookid} Remove an existing subscribed Webhook
GET /api/v1/webhooks/ Get all your current registered and active Webhooks. Pagination is currently not supported
GET /api/v1/webhooks/{WebhookId} Get the specification that belongs to a registered Webhook
POST /api/v1/webhooks/{WebhookId}/test Test the Webhook service with the provided Webhook identifier

Create Webhook

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”.

URL

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

Request body

Field Type Description
trackingId string

Required.

event_groups string

Required.

configuration object

Required.

  url string

Required.

  content_type string

Optional.

  headers array

Optional.

    key string

Required.

    value string

Required. This value will not be available in any response

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

Responses

HTTP status code 201

Returns the registered Webhook after creation request.

Field Type Description
id string

Optional. Represents an unique identifiaction

authenticator string

Optional. Represents your authentication identification

trackingId string

Required.

event_groups string

Required. Represents the group(s) that is part of this Webhook

expiry datetime

Optional. TimeZone is set to UTC. Use this format to parse the instant; yyyy-MM-dd'T'HH:mm:ssZ

created datetime

Optional. TimeZone is set to UTC. Use this format to parse the instant; yyyy-MM-dd'T'HH:mm:ssZ

configuration object

Required.

  url string

Required.

  content_type string

Optional.

  headers array

Optional.

    key string

Required.

    value string

Required. This value will not be available in any response

{
  "id": "1234abc-abcd-1234-5678-abcd1234abcd",
  "authenticator": "1234abc-abcd-1234-5678-abcd1234abcd",
  "configuration": {
    "url": "http://localhost:8888/some/random/location",
    "content_type": "application/json",
    "headers": [
      {
        "key": "x-protection-header"
      },
      {
        "key": "x-protection-header-2"
      }
    ]
  },
  "trackingId": "TESTPACKAGEDELIVERED",
  "event_groups": ["DELIVERED"],
  "expiry": "2019-04-13T05:41:49+0000",
  "created": "2019-03-14T06:41:49+0000"
}

HTTP status code 400

Unable to register Webhook due to some bad request from the client side.

Field Type Description
uuid string

Required. This represents an unique identifier for the failing request. Can be used whilst contacting Bring

status string

Required. Represents a 3/4 digit code that can be used to identify the problem

reason string

Optional. Can contain some hints on what went wrong during the request

{
  "uuid": "KFCtYw",
  "status": "400",
  "reason": "Reference is not provided"
}

HTTP status code 401

Missing authentication headers

HTTP status code 409

Webhook of similar subscription already exists

HTTP status code 429

This may happen due to client sending too many requests. Try again a bit later, or decrease amount of requests

HTTP status code 500

If this happens, try again a bit later as it might be due to some internal mechanism not working

Create multiple 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”.

URL

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

Request body

Field Type Description
trackingIds array

Required.

event_groups string

Required.

configuration object

Required.

  url string

Required.

  content_type string

Optional.

  headers array

Optional.

    key string

Required.

    value string

Required. This value will not be available in any response

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

Responses

HTTP status code 201

Returns the registered Webhook after creation request.

Field Type Description
id string

Optional. Represents an unique identifiaction

authenticator string

Optional. Represents your authentication identification

trackingId string

Required.

event_groups string

Required. Represents the group(s) that is part of this Webhook

expiry datetime

Optional. TimeZone is set to UTC. Use this format to parse the instant; yyyy-MM-dd'T'HH:mm:ssZ

created datetime

Optional. TimeZone is set to UTC. Use this format to parse the instant; yyyy-MM-dd'T'HH:mm:ssZ

configuration object

Required.

  url string

Required.

  content_type string

Optional.

  headers array

Optional.

    key string

Required.

    value string

Required. This value will not be available in any response

[
  {
    "id": "111111-222222-33333-4444-7777777",
    "authenticator": "1234-56789-123-123123123-12312312",
    "configuration": {
      "url": "http://localhost:8888/some/random/location",
      "content_type": "application/json",
      "headers": [
        {
          "key": "x-protection-header"
        },
        {
          "key": "x-protection-header-2"
        }
      ]
    },
    "trackingId": "TESTPACKAGEDELIVERED",
    "event_groups": ["DELIVERED", "IN_TRANSIT"],
    "expiry": "2019-04-13T05:41:49+0000",
    "created": "2019-03-14T06:41:49+0000"
  },
  {
    "id": "111111-222222-33333-4444-555555555",
    "authenticator": "1234-56789-123-123123123-12312312",
    "configuration": {
      "url": "http://localhost:8888/some/random/location",
      "content_type": "application/json",
      "headers": [
        {
          "key": "x-protection-header"
        },
        {
          "key": "x-protection-header-2"
        }
      ]
    },
    "trackingId": "TESTPACKAGEDELIVERED",
    "event_groups": ["DELIVERED", "IN_TRANSIT"],
    "expiry": "2019-04-13T05:41:49+0000",
    "created": "2019-03-14T06:41:49+0000"
  }
]

HTTP status code 400

Unable to register Webhook due to some bad request from the client side.

Field Type Description
uuid string

Required. This represents an unique identifier for the failing request. Can be used whilst contacting Bring

status string

Required. Represents a 3/4 digit code that can be used to identify the problem

reason string

Optional. Can contain some hints on what went wrong during the request

{
  "uuid": "KFCtYw",
  "status": "400",
  "reason": "Reference is not provided"
}

HTTP status code 401

Missing authentication headers

HTTP status code 429

This may happen due to client sending too many requests. Try again a bit later, or decrease amount of requests

HTTP status code 500

If this happens, try again a bit later as it might be due to some internal mechanism not working

Delete Webhook

URL

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

Request params

URI parameter Type Description
Webhookid string

Required. WebhookId. This represents the specific identifier of the Webhook

Query param Type Description
includeWebhook boolean

Optional. If set to true, the deleted Webhook will be returned


Example: true

Responses

HTTP status code 200

Field Type Description
id string

Optional. Represents an unique identifiaction

authenticator string

Optional. Represents your authentication identification

trackingId string

Required.

event_groups string

Required. Represents the group(s) that is part of this Webhook

expiry datetime

Optional. TimeZone is set to UTC. Use this format to parse the instant; yyyy-MM-dd'T'HH:mm:ssZ

created datetime

Optional. TimeZone is set to UTC. Use this format to parse the instant; yyyy-MM-dd'T'HH:mm:ssZ

configuration object

Required.

  url string

Required.

  content_type string

Optional.

  headers array

Optional.

    key string

Required.

    value string

Required. This value will not be available in any response

{
  "id": "1234abc-abcd-1234-5678-abcd1234abcd",
  "authenticator": "1234abc-abcd-1234-5678-abcd1234abcd",
  "configuration": {
    "url": "http://localhost:8888/some/random/location",
    "content_type": "application/json",
    "headers": [
      {
        "key": "x-protection-header"
      },
      {
        "key": "x-protection-header-2"
      }
    ]
  },
  "trackingId": "TESTPACKAGEDELIVERED",
  "event_groups": ["DELIVERED"],
  "expiry": "2019-04-13T05:41:49+0000",
  "created": "2019-03-14T06:41:49+0000"
}

HTTP status code 204

Webhook unregistered and removed. No content supplied in response

HTTP status code 401

Missing authentication headers

HTTP status code 404

Webhook not found (not registered?)

Get all Webhooks

URL

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

Responses

HTTP status code 200

Field Type Description
id string

Optional. Represents an unique identifiaction

authenticator string

Optional. Represents your authentication identification

trackingId string

Required.

event_groups string

Required. Represents the group(s) that is part of this Webhook

expiry datetime

Optional. TimeZone is set to UTC. Use this format to parse the instant; yyyy-MM-dd'T'HH:mm:ssZ

created datetime

Optional. TimeZone is set to UTC. Use this format to parse the instant; yyyy-MM-dd'T'HH:mm:ssZ

configuration object

Required.

  url string

Required.

  content_type string

Optional.

  headers array

Optional.

    key string

Required.

    value string

Required. This value will not be available in any response

[
  {
    "id": "111111-222222-33333-4444-7777777",
    "authenticator": "1234-56789-123-123123123-12312312",
    "configuration": {
      "url": "http://localhost:8888/some/random/location",
      "content_type": "application/json",
      "headers": [
        {
          "key": "x-protection-header"
        },
        {
          "key": "x-protection-header-2"
        }
      ]
    },
    "trackingId": "TESTPACKAGEDELIVERED",
    "event_groups": ["DELIVERED", "IN_TRANSIT"],
    "expiry": "2019-04-13T05:41:49+0000",
    "created": "2019-03-14T06:41:49+0000"
  },
  {
    "id": "111111-222222-33333-4444-555555555",
    "authenticator": "1234-56789-123-123123123-12312312",
    "configuration": {
      "url": "http://localhost:8888/some/random/location",
      "content_type": "application/json",
      "headers": [
        {
          "key": "x-protection-header"
        },
        {
          "key": "x-protection-header-2"
        }
      ]
    },
    "trackingId": "TESTPACKAGEDELIVERED",
    "event_groups": ["DELIVERED", "IN_TRANSIT"],
    "expiry": "2019-04-13T05:41:49+0000",
    "created": "2019-03-14T06:41:49+0000"
  }
]

HTTP status code 400

Unable to register Webhook due to some bad request from the client side.

Field Type Description
uuid string

Required. This represents an unique identifier for the failing request. Can be used whilst contacting Bring

status string

Required. Represents a 3/4 digit code that can be used to identify the problem

reason string

Optional. Can contain some hints on what went wrong during the request

{
  "uuid": "KFCtYw",
  "status": "400",
  "reason": "Reference is not provided"
}

HTTP status code 401

Missing authentication headers.

HTTP status code 404

Webhook not found (not registered?)

Get single Webhook

URL

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

Request params

URI parameter Type Description
WebhookId string

Required. This represents the specific identifier of the Webhook

Responses

HTTP status code 200

Field Type Description
id string

Optional. Represents an unique identifiaction

authenticator string

Optional. Represents your authentication identification

trackingId string

Required.

event_groups string

Required. Represents the group(s) that is part of this Webhook

expiry datetime

Optional. TimeZone is set to UTC. Use this format to parse the instant; yyyy-MM-dd'T'HH:mm:ssZ

created datetime

Optional. TimeZone is set to UTC. Use this format to parse the instant; yyyy-MM-dd'T'HH:mm:ssZ

configuration object

Required.

  url string

Required.

  content_type string

Optional.

  headers array

Optional.

    key string

Required.

    value string

Required. This value will not be available in any response

{
  "id": "1234abc-abcd-1234-5678-abcd1234abcd",
  "authenticator": "1234abc-abcd-1234-5678-abcd1234abcd",
  "configuration": {
    "url": "http://localhost:8888/some/random/location",
    "content_type": "application/json",
    "headers": [
      {
        "key": "x-protection-header"
      },
      {
        "key": "x-protection-header-2"
      }
    ]
  },
  "trackingId": "TESTPACKAGEDELIVERED",
  "event_groups": ["DELIVERED"],
  "expiry": "2019-04-13T05:41:49+0000",
  "created": "2019-03-14T06:41:49+0000"
}

HTTP status code 400

Unable to register Webhook due to some bad request from the client side.

Field Type Description
uuid string

Required. This represents an unique identifier for the failing request. Can be used whilst contacting Bring

status string

Required. Represents a 3/4 digit code that can be used to identify the problem

reason string

Optional. Can contain some hints on what went wrong during the request

{
  "uuid": "KFCtYw",
  "status": "400",
  "reason": "Reference is not provided"
}

HTTP status code 401

Missing authentication headers

HTTP status code 404

Webhook not found (not registered?)

Test a push Webhook

This will trigger a Webhook to receive a dummy request to the registered Webhook.

Note: There is no retry mechanism in place for this, so if a request fails for some reason, it will go on un-noticed.

URL

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

Request params

URI parameter Type Description
WebhookId string

Required. This represents the specific identifier of the Webhook

Responses

HTTP status code 202

The request have been registered, and a dummy-request will be sent to the registered Webhook

HTTP status code 401

Missing authentication headers

HTTP status code 404

Webhook not found (not registered?)