# Webhooks (/integrations/webhooks)

A webhook sends a project's activity to a URL of yours as it happens: your own server, a [Zapier](/integrations/zapier/) Zap or an [n8n](/integrations/n8n/) workflow. Every plan includes webhooks.

## Add a webhook [#add-a-webhook]

<Steps>

1. In the dashboard, open the project → **Integrations** → **Add** → **Webhook**.

2. Enter the URL. It must start with `https://` and be on a public host.

3. Pick its events and, optionally, which feedback sessions.

4. Copy the signing secret. Click the webhook's name to open its page: **Signing secret** shows it again, with **Rotate** beside it for a new one. Any member can see it.

5. Open **⋯** → **Send test event**: Annoty sends a sample `comment.created` with `"test": true`.

</Steps>

## What Annoty sends [#what-annoty-sends]

One `POST` per event, with a JSON body:

```json
{
  "id": "evt_4k9x0c2m7q1d8f3b",
  "type": "comment.created",
  "occurredAt": "2026-10-13T09:24:11.402Z",
  "organizationId": "org_…",
  "projectId": "prj_8d2k1m0x7q3c",
  "feedbackSessionId": "fbs_3k9x0c2m7q1z",
  "actor": { "userId": null, "name": "Sam" },
  "data": {
    "comment": {
      "id": "com_7f2k9q",
      "number": 12,
      "pagePath": "/pricing",
      "body": "The heading wraps on my phone",
      "authorName": "Sam",
      "authorUserId": null,
      "parentId": null,
      "status": "open"
    }
  },
  "test": false,
  "feedbackSession": {
    "id": "fbs_3k9x0c2m7q1z",
    "label": "Homepage review",
    "proxyUrl": "https://homepage-review-k3x9.annoty.site",
    "dashboardUrl": "https://dash.annoty.app/feedback-sessions/fbs_3k9x0c2m7q1z"
  }
}
```

| `type`                         | `data`                                                                      |
| ------------------------------ | --------------------------------------------------------------------------- |
| `comment.created`              | `comment`: a new thread                                                     |
| `comment.replied`              | `comment`: the reply; `thread`: the comment it answers                      |
| `comment.resolved`             | `comment`                                                                   |
| `comment.reopened`             | `comment`                                                                   |
| `feedback_session.created`     | `feedbackSession`: its `id`, `label` and `slug` (null without a proxy link) |
| `feedback_session.deactivated` | `feedbackSession`                                                           |
| `feedback_session.expired`     | `feedbackSession`                                                           |
| `feedback_session.deleted`     | `feedbackSession`. `proxyUrl` and `dashboardUrl` are null: it's gone        |

`number` is the pin number reviewers see, null for a reply. `proxyUrl` is null for a feedback session without a proxy link. New fields may appear; existing ones keep their names.

## Check the signature [#check-the-signature]

Annoty signs every request the [Standard Webhooks](https://www.standardwebhooks.com/) way, so a library does the checking for you:

| Header              | Value                                                                    |
| ------------------- | ------------------------------------------------------------------------ |
| `webhook-id`        | The event's `id`. The same on every retry: skip an id you've already had |
| `webhook-timestamp` | When this attempt was sent, in seconds since 1970                        |
| `webhook-signature` | `v1,` and an HMAC-SHA256 of `id.timestamp.body` with your secret         |

In Node, with the `standardwebhooks` package:

```ts
import { Webhook } from "standardwebhooks";

const webhook = new Webhook(process.env.ANNOTY_WEBHOOK_SECRET!);

export async function POST(request: Request) {
  const body = await request.text();
  // Throws unless Annoty signed this exact body in the last 5 minutes
  const event = webhook.verify(body, Object.fromEntries(request.headers));
  if (event.test) return new Response(null, { status: 204 });
  // …
  return new Response(null, { status: 204 });
}
```

Check the raw body before parsing it: re-serialized JSON won't match the signature. The Standard Webhooks site lists libraries for Python, Go, Ruby, PHP, Java and more.

## Answer quickly [#answer-quickly]

Annoty counts any `2xx` answer within 10 seconds as delivered. After any other answer, no answer or a timeout, Annoty tries again after 5 seconds, 5 minutes, 30 minutes, 2 hours, 5 hours, 10 hours and 10 hours: eight tries over about a day. A `429` with a `Retry-After` header waits at least that long.

<Callout type="idea">
  Answering `410 Gone` turns the webhook off right away. Turn it back on under
  **⋯** → **Edit** → **Active** when you're ready for deliveries again.
</Callout>

Do slow work after you answer. A request that timed out for Annoty may still have reached you, so its retry can be a duplicate: skip any `webhook-id` you've handled.

## Delivery log [#delivery-log]

Click the webhook's name under **Integrations** to open its page. **Deliveries** there lists what Annoty sent in the last 30 days: the body, every attempt with your server's status code, the start of its response and how long it took, and when the next retry runs. **Redeliver** sends a delivery again from the start of the schedule, with the same `webhook-id`.

The [REST API](/api/) has the same: `GET /v1/notification-destinations/{id}/deliveries` and `POST /v1/notification-deliveries/{id}/redeliver`.
