> ## Documentation Index
> Fetch the complete documentation index at: https://docs.poddata.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Have PodData send each new match, correction and change to a company's data to your own address, signed, and retried until it's taken.

A webhook sends each event to an address of yours as it happens: a tracker's new match, a correction to a quote you were sent, or a company's data being created, changed or deleted. A plan with webhooks is in [Keys and limits](https://docs.poddata.ai/keys-and-limits.md).

## 1. Register an address

```bash theme={null}
curl -s -X POST https://api.poddata.ai/v1/webhooks \
  -H "Authorization: Bearer $PODDATA_API_KEY" -H 'Content-Type: application/json' \
  -d '{"url": "https://hooks.lakeside-capital.example/poddata", "events": ["match.created", "quote.corrected"]}'
```

The answer gives the webhook's `id` and its `secret`, which starts `whsec_` and is shown this once. Keep the secret where your receiver reads it, never in code or a log.

* `events` picks what's sent: `match.created`, `quote.corrected`, and a company's data, such as `document.created` or `event.updated`.
* `companies` narrows a company's data to the companies you name, by id; `watch_list: true` to the companies a person on the watch list leads.

## 2. Test it

`POST /webhooks/{id}/test` sends a `ping` now and answers whether your address took it, with its status.

## 3. Take each event

Each event is a `POST` to your address with a JSON body:

```json theme={null}
{
  "id": "evt_01JD9T4V5W6X00000000000000",
  "type": "match.created",
  "created": "2026-11-20T14:03:11Z",
  "data": { "match": { }, "tracker": { }, "quote": { } }
}
```

A `match.created` for a passage a company wrote has `match.mode` `written`, a `passage` and `quote` null; for a post, `posted` and a `post`. The event's `id` is the same on every try, so take each `id` once.

## 4. Check the signature

Every event carries `X-PodData-Signature: t=<unix seconds>,v1=<hex>`. `v1` is the HMAC-SHA256 of `<t>.<body>` with the webhook's secret, over the body exactly as it arrived. Refuse an event whose `t` is more than five minutes old, or whose `v1` isn't yours.

```js theme={null}
import { createHmac, timingSafeEqual } from 'node:crypto';

// body: the raw body, as a string, before any JSON parsing. secret: the webhook's whsec_… secret, from the environment.
export function verified(header, body, secret, now = Date.now()) {
  const parts = Object.fromEntries(header.split(',').map((part) => part.split('=')));
  const t = Number(parts.t);
  if (!Number.isFinite(t) || Math.abs(now / 1000 - t) > 300) return false;
  const expected = createHmac('sha256', secret).update(`${t}.${body}`).digest('hex');
  return parts.v1?.length === expected.length && timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected));
}
```

## 5. Answer quickly

Answer with any `2xx` within 10 seconds, and do the work after. An answer other than `2xx`, or none in 10 seconds, is tried again after 1 minute, 5 minutes, 30 minutes, 2 hours and 12 hours; after the sixth try the event fails. A redirect counts as a failure and isn't followed.

After 20 failures in a row, PodData turns the webhook off and fails the events still waiting for it, and `GET /webhooks` shows it `disabled`, with `failures` and `disabled_at`. Turning it back on, `PATCH /webhooks/{id}` with `{"disabled": false}`, sends new events only.

| To | Route |
| - | - |
| Register one | `POST /webhooks` |
| List them | `GET /webhooks` |
| Change one, or turn it back on | `PATCH /webhooks/{id}` |
| Send it a ping | `POST /webhooks/{id}/test` |
| Delete one | `DELETE /webhooks/{id}` |

No MCP tool registers a webhook: an assistant receives none.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.