Skip to main content
developer

Event Cast API

Released Event Cast API, an API for getting event updates pushed instead of polling tracking.

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
configuration object Required
content_type string OptionalThis value can be maximum 40 characters long
headers array OptionalThe combined length of all the keys and values of header can be maximum 1024 characters long(including the separators)
key string Required
value string RequiredThis value will not be available in any response
url string RequiredThis value can be maximum 250 characters long
event_groups string Required
trackingId string Required 
{
  "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
authenticator string OptionalRepresents your authentication identification. This value can be maximum 40 characters long
configuration object Required
content_type string OptionalThis value can be maximum 40 characters long
headers array OptionalThe combined length of all the keys and values of header can be maximum 1024 characters long(including the separators)
key string Required
value string RequiredThis value will not be available in any response
url string RequiredThis value can be maximum 250 characters long
created datetime OptionalTimeZone is set to UTC. Use this format to parse the instant; yyyy-MM-dd'T'HH:mm:ssZ
event_groups string RequiredRepresents the group(s) that is part of this Webhook
expiry datetime OptionalTimeZone is set to UTC. Use this format to parse the instant; yyyy-MM-dd'T'HH:mm:ssZ
id string OptionalRepresents an unique identifiaction. This value can be maximum 36 characters long
trackingId string Required 
{
  "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
reason string OptionalCan contain some hints on what went wrong during the request
status string RequiredRepresents a 3/4 digit code that can be used to identify the problem
uuid string RequiredThis represents an unique identifier for the failing request. Can be used whilst contacting Bring 
{
  "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
configuration object Required
content_type string OptionalThis value can be maximum 40 characters long
headers array OptionalThe combined length of all the keys and values of header can be maximum 1024 characters long(including the separators)
key string Required
value string RequiredThis value will not be available in any response
url string RequiredThis value can be maximum 250 characters long
event_groups string Required
trackingIds array Required 
{
  "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
authenticator string OptionalRepresents your authentication identification. This value can be maximum 40 characters long
configuration object Required
content_type string OptionalThis value can be maximum 40 characters long
headers array OptionalThe combined length of all the keys and values of header can be maximum 1024 characters long(including the separators)
key string Required
value string RequiredThis value will not be available in any response
url string RequiredThis value can be maximum 250 characters long
created datetime OptionalTimeZone is set to UTC. Use this format to parse the instant; yyyy-MM-dd'T'HH:mm:ssZ
event_groups string RequiredRepresents the group(s) that is part of this Webhook
expiry datetime OptionalTimeZone is set to UTC. Use this format to parse the instant; yyyy-MM-dd'T'HH:mm:ssZ
id string OptionalRepresents an unique identifiaction. This value can be maximum 36 characters long
trackingId string Required 
[
  {
    "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
reason string OptionalCan contain some hints on what went wrong during the request
status string RequiredRepresents a 3/4 digit code that can be used to identify the problem
uuid string RequiredThis represents an unique identifier for the failing request. Can be used whilst contacting Bring 
{
  "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 parameters

URI param 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
authenticator string OptionalRepresents your authentication identification. This value can be maximum 40 characters long
configuration object Required
content_type string OptionalThis value can be maximum 40 characters long
headers array OptionalThe combined length of all the keys and values of header can be maximum 1024 characters long(including the separators)
key string Required
value string RequiredThis value will not be available in any response
url string RequiredThis value can be maximum 250 characters long
created datetime OptionalTimeZone is set to UTC. Use this format to parse the instant; yyyy-MM-dd'T'HH:mm:ssZ
event_groups string RequiredRepresents the group(s) that is part of this Webhook
expiry datetime OptionalTimeZone is set to UTC. Use this format to parse the instant; yyyy-MM-dd'T'HH:mm:ssZ
id string OptionalRepresents an unique identifiaction. This value can be maximum 36 characters long
trackingId string Required 
{
  "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/

Request parameters

Query param Type Description
limit string Optional This represents the limit which can be used to limit the number of latest webhooks returned. Max limit for this is 150 000.
Default value: 10000
Example: 100

Responses

HTTP status code 200

Field Type Description
authenticator string OptionalRepresents your authentication identification. This value can be maximum 40 characters long
configuration object Required
content_type string OptionalThis value can be maximum 40 characters long
headers array OptionalThe combined length of all the keys and values of header can be maximum 1024 characters long(including the separators)
key string Required
value string RequiredThis value will not be available in any response
url string RequiredThis value can be maximum 250 characters long
created datetime OptionalTimeZone is set to UTC. Use this format to parse the instant; yyyy-MM-dd'T'HH:mm:ssZ
event_groups string RequiredRepresents the group(s) that is part of this Webhook
expiry datetime OptionalTimeZone is set to UTC. Use this format to parse the instant; yyyy-MM-dd'T'HH:mm:ssZ
id string OptionalRepresents an unique identifiaction. This value can be maximum 36 characters long
trackingId string Required 
[
  {
    "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
reason string OptionalCan contain some hints on what went wrong during the request
status string RequiredRepresents a 3/4 digit code that can be used to identify the problem
uuid string RequiredThis represents an unique identifier for the failing request. Can be used whilst contacting Bring 
{
  "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 parameters

URI param Type Description
WebhookId string Required This represents the specific identifier of the Webhook

Responses

HTTP status code 200

Field Type Description
authenticator string OptionalRepresents your authentication identification. This value can be maximum 40 characters long
configuration object Required
content_type string OptionalThis value can be maximum 40 characters long
headers array OptionalThe combined length of all the keys and values of header can be maximum 1024 characters long(including the separators)
key string Required
value string RequiredThis value will not be available in any response
url string RequiredThis value can be maximum 250 characters long
created datetime OptionalTimeZone is set to UTC. Use this format to parse the instant; yyyy-MM-dd'T'HH:mm:ssZ
event_groups string RequiredRepresents the group(s) that is part of this Webhook
expiry datetime OptionalTimeZone is set to UTC. Use this format to parse the instant; yyyy-MM-dd'T'HH:mm:ssZ
id string OptionalRepresents an unique identifiaction. This value can be maximum 36 characters long
trackingId string Required 
{
  "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
reason string OptionalCan contain some hints on what went wrong during the request
status string RequiredRepresents a 3/4 digit code that can be used to identify the problem
uuid string RequiredThis represents an unique identifier for the failing request. Can be used whilst contacting Bring 
{
  "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 parameters

URI param 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?)