Event Cast API – Bring Developer

Endpoints

Base URL

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

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

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

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.

Response format
Example: Registered Webhook

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.

Response format
Example: Invalid creation request

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

Request format
Example: Valid Request

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.

Response format
Example: Registered Webhook

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.

Response format
Example: Invalid creation request

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

Response format
Example: Registered Webhook

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

Response format
Example: Registered Webhook

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.

Response format
Example: Invalid creation request

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

Response format
Example: Registered Webhook

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.

Response format
Example: Invalid creation request

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