Webhooks

Osintly can push a lightweight search completion notification to your server. You configure the webhook when creating a search (POST /search) with the delivery.webhook object:

{
  "query": {
    "type": "Email Address",
    "value": "[email protected]"
  },
  "delivery": {
    "webhook": {
      "url": "https://client.example/webhooks/osintly",
      "secret": "super-secret-webhook-key"
    }
  }
}

When a webhook is sent

A webhook is attempted after the search reaches a terminal status:

finished
error

If no delivery.webhook.url is provided at search creation, no callback is sent.

What your webhook endpoint receives

Your endpoint receives a JSON payload with the following shape:

{
  "searchId": "4a8cbb96-70df-4bd6-8f4a-9c0bf5ffde1f",
  "status": "finished",
  "finishedAt": "2026-03-03T14:21:30.120Z",
  "search": {
    "id": "4a8cbb96-70df-4bd6-8f4a-9c0bf5ffde1f",
    "value": "[email protected]",
    "type": "Email Address",
    "options": {
      "include_registered_accounts": true
    },
    "created_at": "2026-03-03T14:20:10.010Z"
  },
  "summary": {
    "module_results": 24,
    "leak_sources": 2,
    "breached_accounts": 1,
    "registered_accounts": 7
  },
  "links": {
    "state": "https://api.osint.ly/search/4a8cbb96-70df-4bd6-8f4a-9c0bf5ffde1f",
    "results": "https://api.osint.ly/search/4a8cbb96-70df-4bd6-8f4a-9c0bf5ffde1f/results",
    "byok": "https://api.osint.ly/search/4a8cbb96-70df-4bd6-8f4a-9c0bf5ffde1f/byok",
    "leaks": "https://api.osint.ly/search/4a8cbb96-70df-4bd6-8f4a-9c0bf5ffde1f/results/leaks"
  }
}

Field reference

Field	Type	Description
`searchId`	`string (uuid)`	Search identifier
`status`	`"finished" \| "error"`	Final normalized status sent by webhook delivery
`finishedAt`	`string (date-time)`	Delivery timestamp
`search.id`	`string (uuid)`	Original search id
`search.value`	`string`	Original search value
`search.type`	`string`	Original search type
`search.options`	`object \| null`	Original request options
`search.created_at`	`string (date-time)`	Original search creation timestamp
`summary.module_results`	`integer`	Count of stored module and normalized BYOK result cards
`summary.leak_sources`	`integer`	Count of successful persisted leak providers
`summary.breached_accounts`	`integer`	Count of breached account entries
`summary.registered_accounts`	`integer`	Count of registered account entries
`links.state`	`string (uri)`	Retrieve the search state
`links.results`	`string (uri)`	Retrieve normalized search results
`links.byok`	`string (uri)`	Retrieve BYOK provider details
`links.leaks`	`string (uri)`	Retrieve leak source overview

Verify authenticity (recommended)

When you define delivery.webhook.secret, verify a signature header on your endpoint. Use this signing format:

Algorithm: HMAC-SHA256
Signed input: timestamp + raw_request_body
Output format: sha256=<hex_digest>

Example verifier (Node.js)

import crypto from "node:crypto";

function sign(secret, timestamp, rawBody) {
  const digest = crypto
    .createHmac("sha256", secret)
    .update(timestamp + rawBody)
    .digest("hex");
  return `sha256=${digest}`;
}

function verifySignature({ secret, timestamp, rawBody, receivedSignature }) {
  const expected = sign(secret, timestamp, rawBody);
  if (expected.length !== receivedSignature.length) return false;
  return crypto.timingSafeEqual(
    Buffer.from(expected, "utf8"),
    Buffer.from(receivedSignature, "utf8")
  );
}

Receiver checklist

Return 2xx quickly after validation
Process heavy work asynchronously
Keep handlers idempotent by deduplicating on searchId
Log and monitor non-2xx responses from your endpoint

Use the webhook as a completion signal, then fetch the full data you need from the links included in the payload.

API Overview

Endpoints

When a webhook is sent

What your webhook endpoint receives

Field reference

Verify authenticity (recommended)

Example verifier (Node.js)

Receiver checklist

​When a webhook is sent

​What your webhook endpoint receives

​Field reference

​Verify authenticity (recommended)

​Example verifier (Node.js)

​Receiver checklist

When a webhook is sent

What your webhook endpoint receives

Field reference

Verify authenticity (recommended)

Example verifier (Node.js)

Receiver checklist