Webhooks

Webhooks let DomChekr push events to your server in real time, so you can react immediately when a domain status changes.

Registering a webhook

Add a webhook endpoint via the API or from Settings → Notifications in the dashboard.

DomChekr sends a ping event to your URL immediately after registration to confirm the endpoint is reachable.

Event payload

All events share the same envelope:

{
  "event": "domain.available",
  "id": "evt_01HX...",
  "created_at": "2025-03-11T13:00:00Z",
  "data": { ... }
}

Event types

Event	Triggered when
domain.available	A monitored domain becomes available
domain.registered	A monitored domain gets registered (was previously available)
domain.expiring	A registered domain expires within 30 days
domain.pending_delete	A domain enters the pending-delete grace period
ping	Sent on webhook registration to verify the endpoint

domain.available payload

{
  "event": "domain.available",
  "id": "evt_01HX...",
  "created_at": "2025-03-11T13:00:00Z",
  "data": {
    "domain": "example.com",
    "watchlist_id": "wl_01HX...",
    "previous_status": "registered",
    "checked_at": "2025-03-11T13:00:00Z"
  }
}

Verifying signatures

Every request includes an X-DomChekr-Signature header, allowing you to verify the payload originated from DomChekr.

The signature is an HMAC-SHA256 hex digest of the raw request body, using your webhook secret as the key. You can find (or regenerate) the secret for each webhook in Settings → Notifications.

Verification example (Node.js)

import crypto from 'node:crypto';

function verifySignature(rawBody, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected),
  );
}

Attention

Always verify the signature before processing an event. Reject requests where the signature does not match.

Responding to events

Your endpoint must return a 2xx status code within 10 seconds. If it times out or returns a non-2xx response, DomChekr retries the delivery with exponential backoff:

Attempt	Delay
1st retry	1 minute
2nd retry	5 minutes
3rd retry	30 minutes
4th retry	2 hours

After 4 failed attempts, the event is marked as failed and no further retries are made. You can view and replay failed events from Settings → Notifications → Webhook logs.

Local testing

Use a tunneling tool like ngrok or cloudflared to expose a local port to the internet during development:

ngrok http 3000
# Forwarding: https://abc123.ngrok-free.app → http://localhost:3000

Then register https://abc123.ngrok-free.app/webhooks/domchekr as your webhook URL in the dashboard.