News API: Webhooks

Beta version

The new News API is still in beta and may be subject to some changes.

In order to be notified with updates on our posts data, our News service offers webhooks.

Instead of constantly polling our API, you can subscribe to the updates that you are interested in (like when a post is created or deleted) and we will notify you when this happens in order to update the precise part of our data at the precise time. An explanation about how webhooks work can be found here.

How to subscribe to posts

In order to manage your post webhooks, we provide you with a set of endpoints:

Webhooks management

The endpoints you subscribe to for certain posts, will receive POST HTTP requests with the post notification you subscribed to.

caution

You should respond our server with a 200 OK or 204 No Content status code. This way, we can know if the request was successful.

Posts

NameDescription
post_createdNew post created
post_updatedNew post updated
post_deletedPost deleted

To see more info about the webhooks posts and their payloads (request body), you can take a look at the API Reference. Open the POST /webhooks endpoint documentation, and examine the Callbacks tab:

Webhooks documentation

There you can find an example of the post_created post, that only sends the ID of the post. This can be used to get the full data of the new post (using our /v4/{culture}/post/{id} endpoint) at the exact moment you are notified of its creation.

{
"type": "post_created",
"id": "5e5f6e2f-7e6f-404e-bd1a-456558f0de11",
"feedId": "5e5f6e2f-7e6f-404e-bd1a-456558f0de11",
"languageId": "5e5f6e2f-7e6f-404e-bd1a-456558f0de11"
}

Debugging webhooks

Tip: Testing on local

To test your webhooks locally, we recommend you to use tools like ngrok to expose your local API instance so that our service can call your test server and you can debug your own code.

Tip: Last successful call

You can use the lastSentAt value of the Webhook object to see the last successful call to that webhook endpoint (last POST request with a 200 OK or 204 No Content response from your side).