Webhooks

What?

Webhooks allow us to push data to you when it is added or updated. Instead of polling the API for changes, you can listen on your HTTP endpoint (Webhook) and we will deliver the data to you.

Webhooks are only available on Pro, Ultra and Enterprise plans.

How to register your webhook

Make a POST request to /webhooks via the IGDB API and include the following HEADER Content-Type: application/json and add a BODY to the request or as url encoded form parameters…

{
    "webhook": {
        "url": "YOUR_WEBHOOK_URL", // url that the data will be sent to.
        "category": 1, // which kind of data you want to receive.
        "secret": "YOUR_SECRET" // we will send this back to you in each request.
    }
}

On registering your webhook you will receive a response like this…

{
    "id": 42, // A unique ID for the webhook
    "url": "YOUR_WEBHOOK_URL", // Your chosen URL
    "category": 1, // Your chosen category
    "last_failed_at": 1510826647000, // When the webhook last failed in unix time
    "secret": "YOUR_SECRET" // Your chosen secret
}

Here is an example request using curl…

curl -X POST \
  https://api-endpoint.igdb.com/webhooks \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'user-key: YOUR_KEY' \
  -d '{
    "webhook": {
        "url": "https://www.igdb.com/test",
        "category": 1,
        "secret": "YOUR_SUPER_SECRET"
    }
}'

That’s it! The data will now be sent to your webhook in the body of a post request. The data is a single json object representing an unexpanded entity, click anything in the category list below for examples.

You can ensure security by checking the X-Secret header in our request against your chosen secret.

Removing a Webhook

  • If a webhook fails to return a 200 OK within 24 hours it will be removed.
  • If a webhook returns 401 Unauthorized it will be removed.
  • You can manually unregister your webhook by sending a DELETE request to /webhooks/ID where ID is the ID returned during the registration process.

Category keys