Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Include updates to documentation for webhooks related to customer fee… #346

Merged
merged 3 commits into from May 16, 2019
Merged

Include updates to documentation for webhooks related to customer fee… #346

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
3f0568f
Include updates to documentation for webhooks related to customer fee…
May 14, 2019
2c62c1e
Include update for events related to not-registered and expired
May 15, 2019
f6c79c2
Include formatting of json example for beautification
May 15, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
81 changes: 59 additions & 22 deletions api/webhooks/api.raml
View file
Open in desktop
Expand Up @@ -53,11 +53,11 @@ types:
expiry:
type: datetime
required: false
description: Populated on fetching existsing Webhook
description: TimeZone is set to UTC. Use this format to parse the instant; `yyyy-MM-dd'T'HH:mm:ssZ`
created:
type: datetime
required: false
description: Populated on fetching existsing Webhook
description: TimeZone is set to UTC. Use this format to parse the instant; `yyyy-MM-dd'T'HH:mm:ssZ`
configuration:
type: Configuration
required: true
Expand Down Expand Up @@ -143,7 +143,9 @@ documentation:
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.

Our available event groups are:
#### Event groups

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

| Event | Description |
|:-------|:--------|
Expand All @@ -167,13 +169,25 @@ documentation:
| `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 |
| `UNKNOWN` | Represents unknown / undefined events |

It is possible to subscribe to multiple event groups. These groups are separated with comma in an array. See the "Create Webhook" section below.
There is also a specific set of events that will be sent if something deviates from the normal event flow:

| Event | Description |
|:-------|:--------|
| `NO_REG` | 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 |

**Note:** As existing subscribed Webhooks is locked for modifications, you will have to delete and recreate the subscription upon changes to the list of subscribed events.
#### Subscribing to multiple event groups

**Note:** Right now we do not support wildcard events (`*` or `ALL`).
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.

- title: Receiving Callbacks
content: |
Expand All @@ -182,6 +196,13 @@ documentation:
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 funcitonality 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"
```

- title: Payload
content: |

Expand Down Expand Up @@ -212,24 +233,24 @@ documentation:
Content-Length: 188

{
"status":"IN_TRANSIT",
"id":"ad84cbca-2e89-43e0-a301-a8d5d7fe7804",
"shipment":"SHIPMENTNUMBER",",
"package":"TESTPACKAGEDELIVERED
"created":"2019-03-16 14:58:48",
"pushed":"2019-03-16 14:58:49"
"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"
}
```
- title: Q & A
content: |

#### Can I have multiple Webhooks for the same parcel?
You can have several Webhooks on the same parcel and/or shipment, as long as the event groups are different.
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 at the same time?
There is no limitation for the moment.
#### How many active Webhooks can I have simultaneously?
Currently there is no limitation.

#### Expiration duration, can I define that?
#### Is the expiration duration configurable?
No.

#### Can I get a history of events that were sent for a subscription?
Expand All @@ -238,15 +259,31 @@ documentation:
#### 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 3 (three) times with a delay on 30 minutes for the two first, then wait an hour for the last retry.
#### 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.

/api/v1/webhooks:
displayName: Create Webhook
description: |
Create a new subscription for a 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".
post:
description: Register a new Webhook subscription for a parcel or shipment
description: Register a new Webhook subscription for a parcel or shipment.
body:
application/json:
type: WebhookRequest
Expand Down Expand Up @@ -290,7 +327,7 @@ documentation:
displayName: Create multiple Webhooks
description: |
Create a range of new Webhooks based on a list of any parcel or shipment.
Webhooks lives for up to one month, or until the entity subscribed for is marked as "delivered by Bring".
Webhooks lives for up to 30 days, or until the entity subscribed for is marked as "delivered by Bring".
post:
description: Register a new Webhook subscription for an array parcels and/or shipments
body:
Expand Down
8 changes: 4 additions & 4 deletions api/webhooks/examples/batch-webhook-request.json
View file
Open in desktop
Expand Up @@ -16,8 +16,8 @@
},
"trackingId": "TESTPACKAGEDELIVERED",
"event_groups": ["DELIVERED", "IN_TRANSIT"],
"expiry": "2019-04-13 05:41:49",
"created": "2019-03-14 06:41:49"
"expiry": "2019-04-13T05:41:49+0000",
"created": "2019-03-14T06:41:49+0000"
},
{
"id": "111111-222222-33333-4444-555555555",
Expand All @@ -36,7 +36,7 @@
},
"trackingId": "TESTPACKAGEDELIVERED",
"event_groups": ["DELIVERED", "IN_TRANSIT"],
"expiry": "2019-04-13 05:41:49",
"created": "2019-03-14 06:41:49"
"expiry": "2019-04-13T05:41:49+0000",
"created": "2019-03-14T06:41:49+0000"
}
]
2 changes: 1 addition & 1 deletion api/webhooks/examples/create-webhook-request.json
View file
Open in desktop
Expand Up @@ -14,5 +14,5 @@
}
]
},
"event_groups": ["DELIVERED"]
"event_groups": ["DELIVERED", "IN_TRANSIT", "DEVIATION"]
}
8 changes: 4 additions & 4 deletions api/webhooks/examples/webhook-request-all.json
View file
Open in desktop
Expand Up @@ -16,8 +16,8 @@
},
"trackingId": "TESTPACKAGEDELIVERED",
"event_groups": ["DELIVERED", "IN_TRANSIT"],
"expiry": "2019-04-13 05:41:49",
"created": "2019-03-14 06:41:49"
"expiry": "2019-04-13T05:41:49+0000",
"created": "2019-03-14T06:41:49+0000"
},
{
"id": "111111-222222-33333-4444-555555555",
Expand All @@ -36,7 +36,7 @@
},
"trackingId": "TESTPACKAGEDELIVERED",
"event_groups": ["DELIVERED", "IN_TRANSIT"],
"expiry": "2019-04-13 05:41:49",
"created": "2019-03-14 06:41:49"
"expiry": "2019-04-13T05:41:49+0000",
"created": "2019-03-14T06:41:49+0000"
}
]
4 changes: 2 additions & 2 deletions api/webhooks/examples/webhook-request.json
View file
Open in desktop
Expand Up @@ -15,6 +15,6 @@
},
"trackingId": "TESTPACKAGEDELIVERED",
"event_groups": ["DELIVERED"],
"expiry": "2019-04-13 05:41:49",
"created": "2019-03-14 06:41:49"
"expiry": "2019-04-13T05:41:49+0000",
"created": "2019-03-14T06:41:49+0000"
}