OpenTrack offers the ability for developers to subscribe to various events that occur in the container lifecycle. When these events occur, we will ping the server defined at the configured webhook URL with data relevant to the event.
In this request, pass in your desired Webhook URL and the events you would like to consume.
If no events are provided, the webhook will include all event types.
See All Webhook Event Types for the list of possible event types to consume.
The API will enforce unique webhook URLs in your account. It will return a VALIDATION_ERROR if an attempt is made to register a webhook with a URL that is already registered.
Using A Secret For Added Security
Optionally, you can specify a secret in the registration request, which we will use to identify webhook requests from OpenTrack. (See Validating Webhooks)
Receiving Webhooks
When these events occur, we will send a POST request to your webhook URL. You can expect these events to have a latency of up to 1 minute of the actual event taking place.
If our POST request to your endpoint fails (meaning we receive a 4xx or 5xx status code in response), then we will retry the same POST request, no more than 30 minutes later, and keep repeating every 30 minutes until:
- We receive a 2xx response from your server.
- We have attempted to reach your server with this webhook event 5 times.
The webhook payload will look like the following:
{
"data": {...},
"changes":
{
"status":
{ "previous": "DISCHARGED", "current": "AVAILABLE" }
},
"deliveryAttempt": 1,
"pendingRetries": 4,
"event": "container.status.updated",
"sentAt": "2019-07-19T17:00:00.654Z"
}
The contents of data vary depending on the webhook event type. Take a look at the Webhooks section of the docs for more details.
Validating Webhooks
In the webhook event request, we will also send a X-OpenTrack-Signature header which can be used to verify that this webhook event is indeed coming from OpenTrack.
To validate, encrypt the incoming webhook payload with your webhook config secret key. Check that this generated signature matches the signature in X-OpenTrack-Signature header.
For example, in Javascript:
const crypto = require("crypto");
const hmac = crypto.createHmac("sha256", secret);
const signature = hmac.update(JSON.stringify(webhookPayload)).digest("hex");