Webhooks
Annoty sends new comments, replies, resolves and feedback session changes to any URL, signed, retried for a day and logged.
A webhook sends a project's activity to a URL of yours as it happens: your own server, a Zapier Zap or an n8n workflow. Every plan includes webhooks.
Add a webhook
-
In the dashboard, open the project → Integrations → Add → Webhook.
-
Enter the URL. It must start with
https://and be on a public host. -
Pick its events and, optionally, which feedback sessions.
-
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.
-
Open ⋯ → Send test event: Annoty sends a sample
comment.createdwith"test": true.
What Annoty sends
One POST per event, with a JSON body:
{
"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
Annoty signs every request the Standard Webhooks 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:
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
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.
Answering 410 Gone turns the webhook off right away. Turn it back on under
⋯ → Edit → Active when you're ready for deliveries again.
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
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 has the same: GET /v1/notification-destinations/{id}/deliveries and POST /v1/notification-deliveries/{id}/redeliver.