Skip to content
RocketVerifierDOCS
POSThttps://api.rocketverifier.com/v1/webhooks

Receive events with webhooks

In short

Register an HTTPS endpoint with POST /v1/webhooks and RocketVerifier POSTs a signed JSON event to it for each subscribed event. Verify the X-RocketVerifier-Signature header (an HMAC SHA-256 of the timestamp and the raw body), answer with any 2xx within 10 seconds, and de-duplicate on the event id. Failed deliveries are retried 5 times over about 26 hours.

OAuth scope webhooks:manage

curl -X POST https://api.rocketverifier.com/v1/webhooks \
  -H "Authorization: Bearer $ROCKETVERIFIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.northwind.io/rocketverifier",
    "events": ["job.completed", "job.failed", "credits.low"],
    "name": "Production"
  }'
Response 200
{
  "id": "cm3k9x2v40001qz8l5h7d2f6a",
  "name": "Production",
  "url": "https://hooks.northwind.io/rocketverifier",
  "events": ["job.completed", "job.failed", "credits.low"],
  "is_active": true,
  "success_count": 0,
  "failure_count": 0,
  "last_triggered_at": null,
  "last_success_at": null,
  "last_failure_at": null,
  "created_at": "2026-11-11T09:42:17.208114+00:00",
  "secret": "Xq3v...store-this-now",
  "signature_header": "X-RocketVerifier-Signature",
  "verification_instructions": "Every delivery is signed. ..."
}

Webhooks push events to your server the moment they happen, so you never poll for a finished job or a low balance. Every delivery is signed, retried on failure and logged for debugging.

Create a webhook#

POST /v1/webhooks registers an HTTPS endpoint for one or more events and returns its signing secret. Store the secret straight away: it is shown only in this response. The webhook endpoints need the webhooks:manage scope and work at any balance.

Body

  • urlstring (uri)required

    The HTTPS URL that receives deliveries. It must be publicly reachable.

  • eventsarray of stringsdefault ["job.completed","job.failed"]

    The events to deliver.

  • namestring

    A label for the endpoint.

The URL must use HTTPS and resolve to a public address. Deliveries never follow redirects, so register the final URL.

List event types#

There are seven events. GET /v1/webhooks/events returns the same list with descriptions and needs no key.

EventFires when
job.completedA bulk job finishes.
job.failedA bulk job fails, including uploads that could not be read.
credits.lowA charge leaves 100 credits or fewer, above zero.
credits.depletedA charge brings the balance to zero.
email.verifiedA single verification with a live key finishes, or a connector verifies a new contact. High volume.
monitor.alertA monitor finds a regression.
integration.sync.completedAn integration sync, re-check or campaign guard run finishes.

New webhooks subscribe to job.completed and job.failed when events is omitted.

Verify the signature#

Every delivery carries an X-RocketVerifier-Signature header of the form t=<unix seconds>,v1=<hex>. v1 is the HMAC SHA-256, keyed with your webhook secret, of the timestamp, a period and the raw request body. To verify a delivery:

  1. Read the raw body bytes. Never verify JSON you parsed and serialized again.
  2. Split the header into t and v1.
  3. Reject the delivery when t is more than 300 seconds from your clock.
  4. Compute HMAC_SHA256(secret, t + "." + raw_body) as hex and compare it with v1 in constant time.

The SDKs do all four steps in one call.

import express from "express";
import { constructWebhookEvent, WebhookSignatureError } from "@rocketverifier/sdk";

const app = express();

app.post("/rocketverifier", express.raw({ type: "application/json" }), (req, res) => {
  let event;
  try {
    event = constructWebhookEvent(
      req.body, // Buffer: the raw body
      req.headers["x-rocketverifier-signature"],
      process.env.ROCKETVERIFIER_WEBHOOK_SECRET
    );
  } catch (err) {
    if (err instanceof WebhookSignatureError) return res.status(400).send(err.reason);
    throw err;
  }

  if (event.event === "job.completed") {
    // queue the download of event.data.job_id
  }
  res.sendStatus(204);
});

Verify without an SDK#

The scheme needs only the standard library.

import crypto from "node:crypto";

export function verifySignature(rawBody, header, secret, toleranceSec = 300) {
  const parts = Object.fromEntries(
    String(header || "").split(",").map((p) => p.trim().split("=", 2))
  );
  const t = parts.t;
  const v1 = parts.v1 || "";
  if (!/^\d+$/.test(t || "")) return false;
  if (Math.abs(Date.now() / 1000 - Number(t)) > toleranceSec) return false;

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${t}.`)
    .update(rawBody) // Buffer or string, exactly as received
    .digest("hex");
  return (
    v1.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1))
  );
}

Delivery headers#

HeaderValue
X-RocketVerifier-Signaturet=<unix seconds>,v1=<hex HMAC SHA-256>. Verify this one.
X-RocketVerifier-TimestampThe same Unix timestamp as t.
X-RocketVerifier-Event-IdThe event id, stable across retries. Also event_id in the body.
X-Webhook-EventThe event name.
X-Webhook-IDThe id of your webhook endpoint.
X-Webhook-Retry0 on the first attempt, then 1 to 5.
X-Webhook-TimestampThe signing time, as ISO 8601.
X-Webhook-SignatureLegacy sha256=<hex> HMAC of the body alone, kept for older integrations.
User-AgentRocketVerifier-Webhook/1.0

Respond and handle retries#

Answer with any 2xx status within 10 seconds. Do the real work in a background queue, so slow processing never turns into a timeout.

Your endpoint returnsWhat happens
2xxDelivered. failure_count resets to 0.
5xx, 429, a timeout or a network errorRetried after 1 minute, 5 minutes, 30 minutes, 2 hours and 24 hours: 6 attempts in all.
Any other 4xxFinal. Not retried.

Delivery is at least once. Store each X-RocketVerifier-Event-Id and skip ids you have already handled. Job events use a fixed id per job and event, so a repeated job.completed for the same job always has the same id.

After 10 failed attempts in a row, the endpoint is disabled (is_active: false) and receives nothing more. Fix it, then re-enable it with is_active: true, which also resets failure_count.

Read event payloads#

Every delivery is a JSON envelope with the same four fields. data depends on the event.

Envelope
{
  "event_id": "0b7e9c52-6a51-5f0e-9a43-2f1c8d7e4b10",
  "event": "job.completed",
  "timestamp": "2026-11-11T10:02:15.480211+00:00",
  "data": {}
}

job.completed and job.failed#

Both carry the job's final counters. For job.failed, status is failed and download_url is null.

data
{
  "job_id": "q3Lw8vR2nK5tY1zA0bC9dE",
  "status": "completed",
  "name": "October signups",
  "total_emails": 1000,
  "processed_emails": 1000,
  "valid_count": 842,
  "invalid_count": 61,
  "risky_count": 19,
  "catch_all_count": 48,
  "disposable_count": 12,
  "unknown_count": 18,
  "created_at": "2026-11-11T09:58:02.114Z",
  "started_at": "2026-11-11T09:58:04.902Z",
  "completed_at": "2026-11-11T10:02:15.301Z",
  "download_url": "/v1/jobs/q3Lw8vR2nK5tY1zA0bC9dE/download"
}

download_url is a path on https://api.rocketverifier.com. Call it with your key, as in download results.

credits.low and credits.depleted#

credits.low fires after every charge that leaves 100 credits or fewer, so expect several while the balance is low. credits.depleted fires when a charge brings the balance to zero, and has no threshold.

data
{
  "credits_remaining": 84,
  "threshold": 100,
  "message": "Your credit balance is low (84 credits remaining)."
}

email.verified#

Sent after each POST /v1/verify with a live key. The values match the verify response, including the result version of that request.

data
{
  "email": "maya@northwind.io",
  "status": "deliverable",
  "sub_status": "none",
  "reason": "accepted_email",
  "score": 97,
  "disposable": "no",
  "accept_all": "no",
  "catch_all_verdict": null,
  "provider": "google.com",
  "did_you_mean": null,
  "verified_at": "2026-11-11T10:02:15Z"
}

Events from connectors that verify new contacts carry email, status, sub_status, score, classification, disposable, accept_all, catch_all_verdict and verified_at, plus source (the platform), integration_id, source_id, contact_id and job_id.

monitor.alert#

Names the monitor and carries the alert: severity (warning or critical), the reasons, and the current and previous results. The monitors page has a full example.

integration.sync.completed#

Sent when an integration sync finishes with at least one contact verified or reused.

FieldMeaning
integration_id, platformWhich integration ran.
sync_log_id, job_idThe sync log and the verification job behind it.
statusHow the run ended, such as completed.
mode, triggerfull, incremental or new_contacts, and what started the run.
countsContacts per classification.
changesContacts whose result changed since the last check.
reusedContacts answered from recent results, at no cost.
updated, failedContacts written back to the platform, and writes that failed.
actions, plannedActions taken, and actions held for your review.
credits_usedNet credits the run used.
completed_atWhen the run finished.

test#

Test deliveries use the event name test, with data set to {"message": "This is a test webhook from RocketVerifier", "webhook_id": "...", "test": true}.

List, get, update and delete webhooks#

All four need the webhooks:manage scope. Secrets are never returned after creation.

GET/v1/webhooks

Returns every endpoint as an array, most recently created first.

GET/v1/webhooks/{webhookId}

Returns one endpoint with its delivery counters.

PATCH/v1/webhooks/{webhookId}

Changes any subset of fields. Sending events replaces the whole subscription.

Body

  • namestring

    A label for the endpoint.

  • urlstring (uri)

    A new HTTPS URL.

  • eventsarray of strings

    Replaces the subscribed events.

  • is_activeboolean

    false pauses deliveries; true resumes them and resets failure_count.

DEL/v1/webhooks/{webhookId}

Deletes the endpoint and its delivery logs, and returns {"success": true, "message": "Webhook deleted"}.

curl -X PATCH https://api.rocketverifier.com/v1/webhooks/cm3k9x2v40001qz8l5h7d2f6a \
  -H "Authorization: Bearer $ROCKETVERIFIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"is_active": true, "events": ["job.completed", "job.failed", "monitor.alert"]}'

Send a test event#

POST /v1/webhooks/{webhookId}/test sends a signed test event to the endpoint right away and reports how it answered. It costs no credits. The call returns 200 even when the delivery fails, so read success.

POST/v1/webhooks/{webhookId}/test
curl -X POST https://api.rocketverifier.com/v1/webhooks/cm3k9x2v40001qz8l5h7d2f6a/test \
  -H "Authorization: Bearer $ROCKETVERIFIER_API_KEY"
Response 200
{
  "success": true,
  "message": "Test webhook delivered successfully! Your endpoint responded with status 204.",
  "status_code": 204,
  "response_time_ms": 182
}

Read delivery logs#

GET /v1/webhooks/{webhookId}/logs lists every delivery attempt, newest first, with your endpoint's status code, the error and the duration. Use it to debug failed deliveries.

GET/v1/webhooks/{webhookId}/logs

Query parameters

  • pageintegermin 1default 1

    Page number, starting at 1.

  • limitinteger1 to 100default 50

    Attempts per page.

  • statusenum

    Only attempts with this outcome.

    pendingsuccessfailedretrying
curl "https://api.rocketverifier.com/v1/webhooks/cm3k9x2v40001qz8l5h7d2f6a/logs?status=failed" \
  -H "Authorization: Bearer $ROCKETVERIFIER_API_KEY"

Rotate the signing secret#

POST /v1/webhooks/{webhookId}/rotate-secret issues a new secret and returns it once. The old secret stops working at once, so deploy the new one to your receiver straight away.

POST/v1/webhooks/{webhookId}/rotate-secret
curl -X POST https://api.rocketverifier.com/v1/webhooks/cm3k9x2v40001qz8l5h7d2f6a/rotate-secret \
  -H "Authorization: Bearer $ROCKETVERIFIER_API_KEY"

Errors#

Statuserror.codeWhen it happens
400invalid_urlThe URL does not use HTTPS.
400invalid_eventsAn event name is not one of the seven events.
400no_changesThe update sent nothing to change.
401unauthorized, api_key_expiredThe key is missing, invalid, revoked or expired.
403insufficient_scopeThe credential lacks webhooks:manage.
404not_foundNo webhook with this id on your account.
422validation_errorurl is missing or a field has the wrong type.

Every error uses the standard error shape.

Frequently asked questions

Why does my signature check fail?

Almost always because the body was parsed and re-serialized before verifying. Compute the HMAC over the exact raw bytes you received, for example with express.raw() in Express or request.get_data() in Flask.

Can the same event arrive twice?

Yes. Delivery is at least once, so a retry can arrive after your endpoint already handled the event. Store the X-RocketVerifier-Event-Id header (also event_id in the body) and skip ids you have seen.

What happens when my endpoint is down?

Each delivery is retried after 1 minute, 5 minutes, 30 minutes, 2 hours and 24 hours. After 10 failed attempts in a row the endpoint is disabled. Fix it, then PATCH it with is_active set to true.

I lost my webhook secret. What now?

Call POST /v1/webhooks/{webhookId}/rotate-secret. It returns a new secret and the old one stops working at once.

Which events fire per verification?

Only email.verified, after every single verification with a live key and for new contacts verified by connectors that emit it. It is high volume, so subscribe to it only when you need it.

Updated 11 November 2026Suggest an edit