# Webhooks · PostLake Docs

> Markdown version of https://postlake.dev/docs/webhooks — canonical page for humans.
> PostLake is the social media API for AI agents: https://postlake.dev/llms.txt

Get told when something happens instead of polling. Register an endpoint and PostLake POSTs an event to it when a post publishes, fails, or an account connects — ideal for scheduled posts and async platforms.

## Register an endpoint

Give PostLake a URL and the events you care about. You get back a `WebhookEndpoint` with a `secret` used to verify deliveries.

```
curl -X POST https://api.postlake.dev/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/hooks/postlake",
    "events": ["post.published", "post.failed"]
  }'
```

## Event types

| Event | Fires when |
| --- | --- |
| `post.published` | Every target of a post has published. |
| `post.partial` | Some targets published, some failed. |
| `post.failed` | No target published. |
| `post.processing` | A post moved to processing (async platforms). |
| `account.connected` | A social account finished connecting. |

## The delivery

PostLake POSTs a JSON body with the event type and the affected resource (the full `Post` for `post.*` events), so you can act without a follow-up API call.

```
{
  "type": "post.published",
  "data": { "id": "post_a1b2c3", "state": "published", "targets": [ … ] }
}
```

## Verify the signature

Every delivery carries a `postlake-signature` header of the form `t=<unix-seconds>,v1=<hex>`. The `v1` value is an HMAC-SHA256 of `<t>.<raw-body>` keyed with your endpoint `secret`. Verify it before trusting the payload — this proves the request really came from PostLake and (with a timestamp tolerance) blocks replays.

**Verify the raw body**, exactly as received — don't parse and re-serialize the JSON first, or the bytes (and the signature) change.

With the SDK it's one call:

```
import { verifyWebhookSignature } from "postlake";

// in your handler — pass the RAW request body
const ok = await verifyWebhookSignature(
  endpointSecret,                     // the secret returned by webhooks.create()
  rawBody,                            // exact bytes received
  req.headers["postlake-signature"],  // the signature header
  { toleranceSec: 300 },              // reject deliveries older than 5 min (optional)
);
if (!ok) return res.status(400).end();
```

Or without the SDK, in plain Node:

```
import { createHmac, timingSafeEqual } from "node:crypto";

function verify(secret, rawBody, header) {
  const { t, v1 } = Object.fromEntries(header.split(",").map(kv => kv.split("=")));
  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  const a = Buffer.from(expected), b = Buffer.from(v1);
  return a.length === b.length && timingSafeEqual(a, b);
}
```

Respond `2xx` quickly once verified; failed deliveries are retried with backoff.

## Managing endpoints

List your endpoints with `GET /v1/webhooks` and remove one with `DELETE /v1/webhooks/{id}`. See the [API reference](https://postlake.dev/docs/api#res-webhooks) for the exact shapes.