https://api.rocketverifier.com/v1/webhooksReceive 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"
}'import RocketVerifier from "@rocketverifier/sdk";
const rv = new RocketVerifier(process.env.ROCKETVERIFIER_API_KEY);
const hook = await rv.webhooks.create({
url: "https://hooks.northwind.io/rocketverifier",
events: ["job.completed", "job.failed", "credits.low"],
name: "Production",
});
// Shown only once: store it as ROCKETVERIFIER_WEBHOOK_SECRET
console.log(hook.secret);import os
from rocketverifier import RocketVerifier
rv = RocketVerifier(os.environ["ROCKETVERIFIER_API_KEY"])
hook = rv.webhooks.create(
"https://hooks.northwind.io/rocketverifier",
events=["job.completed", "job.failed", "credits.low"],
name="Production",
)
# Shown only once: store it as ROCKETVERIFIER_WEBHOOK_SECRET
print(hook.secret){
"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
The HTTPS URL that receives deliveries. It must be publicly reachable.
The events to deliver.
- namestring
A label for the endpoint.
- idstring
- namestring or null
- urlstring (uri)
- eventsarray of strings
The subscribed events.
- is_activeboolean
False when paused, or after 10 failed attempts in a row.
- success_countinteger
Successful delivery attempts.
- failure_countinteger
Failed attempts since the last success.
- last_triggered_atstring (date-time) or null
- last_success_atstring (date-time) or null
- last_failure_atstring (date-time) or null
- created_atstring (date-time)
- secretstring
The signing secret, shown only this once.
The header that carries the signature.
Plain text instructions with sample verification code.
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.
| Event | Fires when |
|---|---|
job.completed | A bulk job finishes. |
job.failed | A bulk job fails, including uploads that could not be read. |
credits.low | A charge leaves 100 credits or fewer, above zero. |
credits.depleted | A charge brings the balance to zero. |
email.verified | A single verification with a live key finishes, or a connector verifies a new contact. High volume. |
monitor.alert | A monitor finds a regression. |
integration.sync.completed | An 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:
- Read the raw body bytes. Never verify JSON you parsed and serialized again.
- Split the header into
tandv1. - Reject the delivery when
tis more than 300 seconds from your clock. - Compute
HMAC_SHA256(secret, t + "." + raw_body)as hex and compare it withv1in 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);
});import os
from flask import Flask, request
from rocketverifier import construct_event, WebhookSignatureError
app = Flask(__name__)
@app.post("/rocketverifier")
def rocketverifier_webhook():
try:
event = construct_event(
request.get_data(), # the raw body bytes
request.headers.get("X-RocketVerifier-Signature", ""),
os.environ["ROCKETVERIFIER_WEBHOOK_SECRET"],
)
except WebhookSignatureError:
return "", 400
if event["event"] == "job.completed":
pass # queue the download of event["data"]["job_id"]
return "", 204Verify 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))
);
}import hashlib
import hmac
import time
def verify_signature(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
parts = dict(p.strip().split("=", 1) for p in (header or "").split(",") if "=" in p)
t, v1 = parts.get("t", ""), parts.get("v1", "")
if not t.isdigit() or abs(time.time() - int(t)) > tolerance:
return False
expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, v1)Delivery headers#
| Header | Value |
|---|---|
X-RocketVerifier-Signature | t=<unix seconds>,v1=<hex HMAC SHA-256>. Verify this one. |
X-RocketVerifier-Timestamp | The same Unix timestamp as t. |
X-RocketVerifier-Event-Id | The event id, stable across retries. Also event_id in the body. |
X-Webhook-Event | The event name. |
X-Webhook-ID | The id of your webhook endpoint. |
X-Webhook-Retry | 0 on the first attempt, then 1 to 5. |
X-Webhook-Timestamp | The signing time, as ISO 8601. |
X-Webhook-Signature | Legacy sha256=<hex> HMAC of the body alone, kept for older integrations. |
User-Agent | RocketVerifier-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 returns | What happens |
|---|---|
2xx | Delivered. failure_count resets to 0. |
5xx, 429, a timeout or a network error | Retried after 1 minute, 5 minutes, 30 minutes, 2 hours and 24 hours: 6 attempts in all. |
Any other 4xx | Final. 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.
{
"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.
{
"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.
{
"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.
{
"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.
| Field | Meaning |
|---|---|
integration_id, platform | Which integration ran. |
sync_log_id, job_id | The sync log and the verification job behind it. |
status | How the run ended, such as completed. |
mode, trigger | full, incremental or new_contacts, and what started the run. |
counts | Contacts per classification. |
changes | Contacts whose result changed since the last check. |
reused | Contacts answered from recent results, at no cost. |
updated, failed | Contacts written back to the platform, and writes that failed. |
actions, planned | Actions taken, and actions held for your review. |
credits_used | Net credits the run used. |
completed_at | When 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.
/v1/webhooksReturns every endpoint as an array, most recently created first.
/v1/webhooks/{webhookId}Returns one endpoint with its delivery counters.
- idstring
- namestring or null
- urlstring (uri)
- eventsarray of strings
The subscribed events.
- is_activeboolean
False when paused, or after 10 failed attempts in a row.
- success_countinteger
Successful delivery attempts.
- failure_countinteger
Failed attempts since the last success.
- last_triggered_atstring (date-time) or null
- last_success_atstring (date-time) or null
- last_failure_atstring (date-time) or null
- created_atstring (date-time)
/v1/webhooks/{webhookId}Changes any subset of fields. Sending events replaces the whole subscription.
Body
/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"]}'const hooks = await rv.webhooks.list();
await rv.webhooks.update("cm3k9x2v40001qz8l5h7d2f6a", {
isActive: true,
events: ["job.completed", "job.failed", "monitor.alert"],
});
await rv.webhooks.delete("cm3k9x2v40001qz8l5h7d2f6a");hooks = rv.webhooks.list()
rv.webhooks.update(
"cm3k9x2v40001qz8l5h7d2f6a",
is_active=True,
events=["job.completed", "job.failed", "monitor.alert"],
)
rv.webhooks.delete("cm3k9x2v40001qz8l5h7d2f6a")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.
/v1/webhooks/{webhookId}/testcurl -X POST https://api.rocketverifier.com/v1/webhooks/cm3k9x2v40001qz8l5h7d2f6a/test \
-H "Authorization: Bearer $ROCKETVERIFIER_API_KEY"const result = await rv.webhooks.test("cm3k9x2v40001qz8l5h7d2f6a");
console.log(result.success, result.statusCode, result.responseTimeMs);result = rv.webhooks.test("cm3k9x2v40001qz8l5h7d2f6a")
print(result.success, result.status_code, result.response_time_ms){
"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.
/v1/webhooks/{webhookId}/logsQuery parameters
Page number, starting at 1.
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"const { logs } = await rv.webhooks.logs("cm3k9x2v40001qz8l5h7d2f6a", { status: "failed" });page = rv.webhooks.logs("cm3k9x2v40001qz8l5h7d2f6a", status="failed")- idstring
- eventstring
- attempt_numberinteger
1 for the first attempt, up to 6.
- statusenumpendingsuccessfailedretrying
- status_codeinteger or null
Your endpoint's HTTP status. Null on a timeout or network error.
- error_messagestring or null
- duration_msinteger or null
- created_atstring (date-time)
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.
/v1/webhooks/{webhookId}/rotate-secretcurl -X POST https://api.rocketverifier.com/v1/webhooks/cm3k9x2v40001qz8l5h7d2f6a/rotate-secret \
-H "Authorization: Bearer $ROCKETVERIFIER_API_KEY"const { secret } = await rv.webhooks.rotateSecret("cm3k9x2v40001qz8l5h7d2f6a");secret = rv.webhooks.rotate_secret("cm3k9x2v40001qz8l5h7d2f6a")["secret"]Errors#
| Status | error.code | When it happens |
|---|---|---|
| 400 | invalid_url | The URL does not use HTTPS. |
| 400 | invalid_events | An event name is not one of the seven events. |
| 400 | no_changes | The update sent nothing to change. |
| 401 | unauthorized, api_key_expired | The key is missing, invalid, revoked or expired. |
| 403 | insufficient_scope | The credential lacks webhooks:manage. |
| 404 | not_found | No webhook with this id on your account. |
| 422 | validation_error | url 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