# Receive events with webhooks

Source: https://docs.rocketverifier.com/api/webhooks
Endpoint: `POST https://api.rocketverifier.com/v1/webhooks` (OAuth scope `webhooks:manage`)

> 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.

cURL:

```bash
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"
  }'
```

Node.js:

```js
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);
```

Python:

```python
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)
```

Response 200:

```json
{
  "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**

| Field | Type | Description |
| --- | --- | --- |
| `url` | string (uri) | The HTTPS URL that receives deliveries. It must be publicly reachable. required |
| `events` | array of strings | The events to deliver. default ["job.completed","job.failed"] |
| `name` | string | A label for the endpoint. |

| Field | Type | Description |
| --- | --- | --- |
| `id` | string |  |
| `name` | string or null |  |
| `url` | string (uri) |  |
| `events` | array of strings | The subscribed events. |
| `is_active` | boolean | False when paused, or after 10 failed attempts in a row. |
| `success_count` | integer | Successful delivery attempts. |
| `failure_count` | integer | Failed attempts since the last success. |
| `last_triggered_at` | string (date-time) or null |  |
| `last_success_at` | string (date-time) or null |  |
| `last_failure_at` | string (date-time) or null |  |
| `created_at` | string (date-time) |  |
| `secret` | string | The signing secret, shown only this once. |
| `signature_header` | string | The header that carries the signature. default "X-RocketVerifier-Signature" |
| `verification_instructions` | string | 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](https://docs.rocketverifier.com/api/monitors) 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:

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.

Node.js:

```js
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);
});
```

Python:

```python
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 "", 204
```

### Verify without an SDK

The scheme needs only the standard library.

Node.js:

```js
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))
  );
}
```

Python:

```python
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](#list-get-update-and-delete-webhooks) 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:

```json
{
  "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:

```json
{
  "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](https://docs.rocketverifier.com/api/batch#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:

```json
{
  "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](https://docs.rocketverifier.com/api/verify#response), including the [result version](https://docs.rocketverifier.com/versioning) of that request.

data:

```json
{
  "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](https://docs.rocketverifier.com/api/monitors#get-alerts-by-webhook) 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](#send-a-test-event) 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.

| Field | Type | Description |
| --- | --- | --- |
| `id` | string |  |
| `name` | string or null |  |
| `url` | string (uri) |  |
| `events` | array of strings | The subscribed events. |
| `is_active` | boolean | False when paused, or after 10 failed attempts in a row. |
| `success_count` | integer | Successful delivery attempts. |
| `failure_count` | integer | Failed attempts since the last success. |
| `last_triggered_at` | string (date-time) or null |  |
| `last_success_at` | string (date-time) or null |  |
| `last_failure_at` | string (date-time) or null |  |
| `created_at` | string (date-time) |  |

`PATCH /v1/webhooks/{webhookId}`

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

**Body**

| Field | Type | Description |
| --- | --- | --- |
| `name` | string | A label for the endpoint. |
| `url` | string (uri) | A new HTTPS URL. |
| `events` | array of strings | Replaces the subscribed events. |
| `is_active` | boolean | `false` pauses deliveries; `true` resumes them and resets `failure_count`. |

`DELETE /v1/webhooks/{webhookId}`

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

cURL:

```bash
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"]}'
```

Node.js:

```js
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");
```

Python:

```python
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`.

`POST /v1/webhooks/{webhookId}/test`

cURL:

```bash
curl -X POST https://api.rocketverifier.com/v1/webhooks/cm3k9x2v40001qz8l5h7d2f6a/test \
  -H "Authorization: Bearer $ROCKETVERIFIER_API_KEY"
```

Node.js:

```js
const result = await rv.webhooks.test("cm3k9x2v40001qz8l5h7d2f6a");
console.log(result.success, result.statusCode, result.responseTimeMs);
```

Python:

```python
result = rv.webhooks.test("cm3k9x2v40001qz8l5h7d2f6a")
print(result.success, result.status_code, result.response_time_ms)
```

Response 200:

```json
{
  "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**

| Field | Type | Description |
| --- | --- | --- |
| `page` | integer | Page number, starting at 1. min 1; default 1 |
| `limit` | integer | Attempts per page. 1 to 100; default 50 |
| `status` | enum | Only attempts with this outcome. one of `pending`, `success`, `failed`, `retrying` |

cURL:

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

Node.js:

```js
const { logs } = await rv.webhooks.logs("cm3k9x2v40001qz8l5h7d2f6a", { status: "failed" });
```

Python:

```python
page = rv.webhooks.logs("cm3k9x2v40001qz8l5h7d2f6a", status="failed")
```

| Field | Type | Description |
| --- | --- | --- |
| `id` | string |  |
| `event` | string |  |
| `attempt_number` | integer | 1 for the first attempt, up to 6. |
| `status` | enum | one of `pending`, `success`, `failed`, `retrying` |
| `status_code` | integer or null | Your endpoint's HTTP status. Null on a timeout or network error. |
| `error_message` | string or null |  |
| `duration_ms` | integer or null |  |
| `created_at` | string (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.

`POST /v1/webhooks/{webhookId}/rotate-secret`

cURL:

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

Node.js:

```js
const { secret } = await rv.webhooks.rotateSecret("cm3k9x2v40001qz8l5h7d2f6a");
```

Python:

```python
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](https://docs.rocketverifier.com/api#handle-errors).

## 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.
