# Skrap.ai webhooks

Webhooks send a signed HTTP POST to your HTTPS endpoint when something happens in Skrap. Add endpoints in the app (Integrations → Webhooks) or subscribe from an integration with the REST-hook endpoints below. Paid plans.

## Events

| Event | When |
| --- | --- |
| `bulk_job.completed` | A bulk verify or bulk find job finished. data: jobId, type, name, total, processed, creditsUsed, statusCounts, resultsUrl. |
| `bulk_job.failed` | A bulk job stopped with an error (processed rows are kept). |
| `credits.low` | Your balance dropped below your alert threshold (once a day at most). data: balance, threshold, plan. |
| `list.lead_added` | A lead was saved to one of your lists. data: listId, listName, lead { fullName, email, emailStatus, title, company, domain, linkedinUrl }. |

## Payload

```json
{
  "id": "evt_65f1c2a9e4b0a1b2c3d4e5f6",
  "type": "bulk_job.completed",
  "created": "2026-11-03T09:12:44.120Z",
  "data": {
    "jobId": "65f1c2a9e4b0a1b2c3d4e5f6",
    "type": "bulk-verify",
    "total": 1200,
    "creditsUsed": 874,
    "statusCounts": { "valid": 801, "risky": 73, "invalid": 290, "unknown": 36 }
  }
}
```

## Headers

| Header | Value |
| --- | --- |
| `Skrap-Event` | Event type, e.g. bulk_job.completed |
| `Skrap-Event-Id` | Same for every delivery of one event — use it to de-duplicate |
| `Skrap-Delivery` | Unique per delivery attempt chain |
| `Skrap-Signature` | t=<unix seconds>,v1=<hex HMAC-SHA256 of `${t}.${raw body}` with your endpoint secret> |

## Verify signatures

```javascript
import crypto from "node:crypto";

function verifySkrapSignature(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false; // replay window
  const expected = crypto.createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1 ?? ""));
}
```

```python
import hmac, hashlib, time

def verify_skrap_signature(raw_body: bytes, header: str, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    if abs(time.time() - int(parts["t"])) > 300:
        return False
    expected = hmac.new(secret.encode(), f"{parts['t']}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts.get("v1", ""))
```

## Retries

Answer 2xx within 10 seconds. Anything else (or a timeout) is retried after 1 min, 5 min, 30 min, 2 h, 6 h and 12 h. Redirects are not followed. An endpoint that fails 50 times in a row is paused — re-enable it in the app.

## REST hooks (for integration builders)

| Method | Path | Description |
| --- | --- | --- |
| POST | `/api/v2/webhooks` | Subscribe: { "url" (or "target_url"), "events": [...] (or "event") } → 201 { id, url, events, secret }. |
| GET | `/api/v2/webhooks` | List subscriptions (no secrets). |
| DELETE | `/api/v2/webhooks/{id}` | Unsubscribe. |
| GET | `/api/v2/webhooks/samples/{event}` | Example payload (array of one) for mapping fields in an integration builder. |
