Choosing webhook event types

Every webhook config has an event_types list. Check sends a config only the event types in that list. A config created without event_types starts with an empty list and receives no webhooks until you select some.

You can manage event_types through the API, as shown on this page, or in Console under Developers > Webhooks by opening the config and clicking Edit event types. Both edit the same list.

Why select event types

• You receive only what your handler processes. Your endpoint doesn't have to accept and discard events it ignores.
• Each endpoint can have its own selection. Register separate configs for separate consumers, or for a gradual cutover from one handler to another, and give each one the event types it needs.
• New event types are opt-in. When Check launches an event type such as payment.created, your configs don't receive it until you add it. A Check launch doesn't change what your integration receives.
• You see deprecations before they affect you. The event type catalog shows when an event type is deprecated, what replaces it, and when it retires, before it stops being supported.

Find the event types you can select

GET /event_types lists every webhook event type:

curl https://api.checkhq.com/event_types \
  -H "Authorization: Bearer <API_KEY>"

An excerpt of the response, for an account whose default API version is 2025-01-01:

{
  "results": [
    {
      "type": "payment.updated",
      "description": "...",
      "status": "supported",
      "selectable": false,
      "unavailable_reason": "Not available in this API version.",
      "replacement": null,
      "migration_guide_url": null,
      "retires_at": null
    },
    {
      "type": "payroll.status_change",
      "description": "...",
      "status": "deprecated",
      "selectable": true,
      "unavailable_reason": null,
      "replacement": "payroll.updated",
      "migration_guide_url": null,
      "retires_at": null
    },
    {
      "type": "payroll.updated",
      "description": "...",
      "status": "supported",
      "selectable": true,
      "unavailable_reason": null,
      "replacement": null,
      "migration_guide_url": null,
      "retires_at": null
    }
  ]
}

The response isn't paginated, and entries are sorted by type. Each entry has these attributes:

Which event types are selectable depends on the API version, and some event types are enabled only for some accounts. By default, the catalog is evaluated at your account's default API version. To see what a specific config can select, pass its ID:

curl -G https://api.checkhq.com/event_types \
  -H "Authorization: Bearer <API_KEY>" \
  --data-urlencode "webhook_config=whc_7uCODm8JFmZyov9jL8QO"

That evaluates the catalog at the config's pinned api_version, or at your account default when the config has none. To evaluate it at another version, for example before you pin a config to it, pass api_version=YYYY-MM-DD instead. You can't pass both parameters in one request.

For what each event's payload contains, see Webhook event types.

Set event types on a config

Pass event_types when you create a webhook config:

curl https://api.checkhq.com/webhook_configs \
  -X POST \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/check/webhooks", "event_types": ["employee.created", "payroll.updated"]}'

To change the selection, update the config. event_types in a PATCH replaces the whole list; it doesn't add to it. Send every event type you want the config to keep:

curl https://api.checkhq.com/webhook_configs/whc_7uCODm8JFmZyov9jL8QO \
  -X PATCH \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/check/webhooks", "event_types": ["employee.created", "employee.updated", "payroll.updated"]}'

To add one event type, read the config's current event_types, append the new name, and send the full list.

Check stores the list without duplicates, sorted by name.

Check what a config receives

Every webhook config response includes event_types. To see a config's selection, fetch it with GET /webhook_configs/{id}.

POST /webhook_configs/{id}/ping sends a test webhook and returns the config, including event_types. A ping is sent whatever the config's event_types contains, so a successful ping proves your endpoint works but not that the config will receive other webhooks. Read event_types in the response to confirm that.

An event_types value of null means the selection was never set, and the config receives every event type. New configs never start with null. Once you set a list, the config receives only what the list contains.

Sandbox and production

Your sandbox and production webhook configs are separate. Set event_types on each config in each environment: a selection made on a sandbox config, through https://sandbox.checkhq.com, doesn't change any production config. See Understanding Sandbox and Production Environments.

Deprecated and retired event types

An event type's status moves from supported to deprecated to retired. When an event type is deprecated, its catalog entry names a replacement and may give a migration_guide_url and a retires_at date. A deprecated event type is still delivered. Move your handler to the replacement and add it to event_types before the deprecated event type retires.

An event type that has become unavailable can stay in a config's saved list. It doesn't block other edits to the config, and you can remove it whenever you send a new list. A retired event type that stays in the list is no longer delivered.

New event types are never added to saved lists. Check the catalog when you upgrade your API version or when Check announces a new event type, and add the ones you want.

When Check rejects an event type

Every event type you add must be selectable for your account at the config's API version. That's the config's pinned api_version, including a version you set in the same request, or your account's default API version when the config has none. If an event type you add isn't selectable, for example because it isn't enabled for your account, the request fails with a 400:

{
  "error": {
    "type": "validation_error",
    "message": "Please correct the required fields and try again.",
    "input_errors": [
      {
        "message": "payment.created is not available for this webhook config.",
        "field": "event_types",
        "field_path": ["event_types"]
      }
    ]
  }
}

A name that isn't an event type at all also fails validation on event_types. To fix either error, call GET /event_types with webhook_config set to the config's ID and choose from the entries where selectable is true. See Errors for the error format.