Events & Payloads

A webhook subscribes to one or more of the events below. The domain events are only sent for domains you have looked up in the last 30 days with an API key in the webhook's environment, so notifications stay limited to domains your application has actually seen.

Available events

domain.flagged.disposable

A domain you have looked up in the last 30 days is newly flagged as disposable.

domain.flagged.relay

Same as above, but for relay domains.

domain.flagged.spam

Same as above, but for spam domains.

domain.unflagged.disposable

A domain you have looked up in the last 30 days changed from disposable: true to disposable: false.

domain.unflagged.relay

Same as above, but for relay domains.

domain.unflagged.spam

Same as above, but for spam domains.

blocklist.domain.created

A domain was added to your account's blocklist.

blocklist.domain.deleted

A domain was removed from your account's blocklist.

Payload

Each event is delivered as a POST request with the following structure:

{
  "event": "domain.flagged.disposable",
  "idempotency_key": "9b2f6c1e-7c25-4a3a-9d4e-1f2a8c3b5d6e",
  "created_at": "2025-03-26T14:30:25+00:00",
  "data": {
    "domain": "example.com"
  }
}

Field	Type	Description
event	string	The type of event that occurred
idempotency_key	string	Identifies the event, and stays the same across every retry of the same delivery
created_at	string	ISO 8601 timestamp of when the event occurred
data	object	Event-specific data. For the events above, the domain concerned

Request headers

Every delivery carries these headers:

Header	Description
X-UserCheck-Signature	HMAC SHA-256 signature for verification. See Security
X-UserCheck-Event-Type	The event type (e.g., domain.flagged.disposable)
X-UserCheck-Delivery-ID	Identifier for this delivery. Stays the same across every retry of the same event
X-UserCheck-Attempt	Which attempt this is, starting at 1
Content-Type	Always application/json
User-Agent	Always UserCheck-Webhook/1.0