Calendar API: Webhooks

In order to be notified with updates on our economic calendar data, our Economic Calendar service offers webhooks.

Instead of constantly polling our API, you can subscribe to the updates that you are interested in (like when an event 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 events

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

Webhooks management

The endpoints you subscribe to for certain events, will receive POST HTTP requests with the event 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.

Limitations

There is a limit of two URLs for new webhook registrations. Once this limit is reached, our API will return a custom HTTP status code [444].

Events

NameDescription
event_createdNew event created
eventDate_createdNew event occurrence created
eventDate_updatedEvent occurrence updated
eventDate_deletedEvent occurrence deleted

To see more info about the webhooks events 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 examples like the eventDate_updated event. You see its payload here:

{
"type": "eventDate_updated",
"eventDateId": "4fe1bd69-acce-4b24-9d54-f45c81708d29",
"eventId": "5e5f6e2f-7e6f-404e-bd1a-456558f0de11",
"lastUpdated": 1628063061,
"changes": [
{
"key": "dateUtc",
"value": "2019-03-21T10:30:00Z"
},
{
"key": "actual",
"value": 0.2
},
{
"key": "revised",
"value": 0.4
}
]
}

There are other cases, like the event_created event, that only sends the ID of the event. This can be used to get the full data of the new event (using our /events/{id} endpoint) at the exact moment you are notified of its creation.

{
"type": "event_created",
"eventId": "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).