HTTP API

Webhooks

It is possible to register a webhook that will be called whenever a content request is modified. You can set the webhook from the Customer Portal and via the API. The webhook will be invoked with a PUT request containing a JSON body, see below for the format. The webhook is invoked for the initial creation of the request and for any state change. For test requests the state will be changed to completed after around 10 seconds.

Note

Webhooks are intended to be used as a complement to synchronizing state. With a webhook it's possible to get updates to requests quicker as changes are pushed to the address specified. Solutions should take care to use synchronization as a complement in case the webhook delivery fails.

Callback format

The webhook format contains a type property and depending on the type more properties that reflect the payload.

For a content request the format is:

{
  "type": "content-request",
  "request": ...content-request...
}
Note

Take extra care to check if the type is content-request on incoming callbacks. More types may be introduced as new features of the API are launched and for future compatibility the type should always be checked.

Failures, retries and guarantees

When a call to a webhook fails due to the server being unreacahable or if the server responds with anything other than a 200 OK the call will be marked as failed. Failed calls are retried perodically with an increasing delay and after 24 hours they will be permanently fail.

The order of which state changes reaches a webhook is not guaranteed. If a webhook call is delayed or failed it might mean that a change to a confirmed state is received after a change to completed. The dates on the request can help with some edge-cases and any errors can be resolved via a regular synchronization.

Update the webhook

PUT https://api.contentor.com/v1/webhook

Webhooks can be set via the Customer portal but can also be updated via the API.

Headers

Authorization: Bearer your-token-here
Content-Type: application/json

Body

{
  "url": "http://example.com/webhook"
}

Response 200 OK

{
  "url": "http://example.com/webhook"
}

Response 400 Bad Request

If the URL is invalid.

{
  "state": "invalid",
  "errors": [
    "..."
  ]
}

Response 403 Forbidden

If no authorization header is sent or if the header is not on the form Bearer your-token-here or if the token is invalid.

Get the current webhook

GET https://api.contentor.com/v1/webhook

Webhooks can be set via the Customer portal but can also be updated via the API.

Headers

Authorization: Bearer your-token-here

Response 200 OK

{
  "url": "http://example.com/webhook"
}

Response 403 Forbidden

If no authorization header is sent or if the header is not on the form Bearer your-token-here or if the token is invalid.