Skip to Content
annotyDocs

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

  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.

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"
  }
}
typedata
comment.createdcomment: a new thread
comment.repliedcomment: the reply; thread: the comment it answers
comment.resolvedcomment
comment.reopenedcomment
feedback_session.createdfeedbackSession: its id, label and slug (null without a proxy link)
feedback_session.deactivatedfeedbackSession
feedback_session.expiredfeedbackSession
feedback_session.deletedfeedbackSession. 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:

HeaderValue
webhook-idThe event's id. The same on every retry: skip an id you've already had
webhook-timestampWhen this attempt was sent, in seconds since 1970
webhook-signaturev1, 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.

On this page