Overview

A webhook pushes a notification to your application when something changes on UserCheck's side: a domain you have looked up is newly flagged as disposable, or an entry is added to your blocklist. Instead of polling the API for changes, your endpoint is called as they happen.

The events available and the payload each one sends are documented in Events & Payloads.

How webhooks work

Webhooks are scoped to an environment. Each of the three environments, development, staging, and production, has its own subscriptions, so a webhook created for development never fires on production traffic.

When an event occurs, UserCheck sends an HTTP POST request to the endpoint URL configured for that environment, carrying the event details as JSON. Every delivery is signed; see Security for how to verify it.

Setting up a webhook

1. Check your API key environment: go to your API keys dashboard and confirm your keys are assigned to the environment you expect
2. Create a webhook: open app.usercheck.com/webhooks
3. Click Add webhook
4. Choose the environment: select which environment the webhook belongs to
5. Enter your endpoint URL: the URL that will receive the deliveries
6. Select events: choose which events to be notified about
7. Click Create

Each webhook has its own signing secret, visible on the webhooks page and regenerable from there. Your endpoint needs it to verify deliveries.

Testing your endpoint

Use the Send test webhook option in the webhook's settings to send a sample payload to your endpoint, so you can confirm it receives deliveries and verifies the signature before real events arrive.

The test delivery is signed like a real one, but its payload is "event": "test.event" with no idempotency_key. A handler that requires that key, or that rejects unknown event types, needs to tolerate the test payload.