Event Cast API
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
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?)