Webhooks

A webhook is an address that Nifty sends a signed POST to each time an event you chose happens, such as when you complete a task, upload a document or add a person. Add a webhook in Settings → Webhooks, or with POST /webhooks (see the Webhooks reference).

Add a webhook

1. In Settings → Webhooks, choose New webhook, or press N.
2. Paste the Address the other app gave you.
3. Choose which events to send. All of them are chosen at first.
4. Choose Add webhook, and then choose Copy secret. You won't be able to see the secret again.

To pause a webhook, use the switch on its row. Choose its name to change it or to see its deliveries. On its page, Send test sends a test event and shows what came back.

Events

Event	Sent when
task.created	A task is added. Only this, whatever its dates.
task.completed	A task is done.
task.deadline_changed, task.start_changed	A task's deadline or start date is added, changed or removed.
task.expired	A task passes its expiry date and is archived.
document.uploaded	A PDF is uploaded.
document.summarized	AI has summarised a document (see AI).
person.created	A person is added.
note.saved	A note is added or changed. While you're writing, at most once a minute, with the note as it is then.

More events will be added, so ignore any type you don't know.

What's sent

Each event is one JSON body. It has its type, when it happened, and, in data, the record as its GET shows it, under task, document, person or note. A changed date also has the date before, in previous.

{
  "id": "01m4tmt3e000ss88yfett8ys9e",
  "type": "task.deadline_changed",
  "created_at": "2026-10-13T12:46:44.672Z",
  "data": {
    "task": { "id": "01m4tmt0zqyx1h20hdje9h6c03", "title": "Book the vet", "deadline_on": "2026-10-22", "…": "…" },
    "previous": { "deadline_on": "2026-10-20" }
  }
}

• Images in notes and people's photos are links that open without signing in, as they do in the app. Anyone who sees the payload can view them.
• One change can send several events, such as completing a task and moving its deadline.
• Each event is sent no more than once, within a few seconds. There's no retry. If the address is down, takes more than 10 seconds or answers with anything other than 2xx, that event is missed. Redirects aren't followed.
• A webhook's page lists its newest 50 deliveries. Choose one to see what was sent, and what came back or why it failed.

Check the signature

Every request has webhook-id, webhook-timestamp and webhook-signature headers. They're signed in the same way as Standard Webhooks, so its libraries can check them.

from standardwebhooks.webhooks import Webhook

Webhook(secret).verify(body, headers)  # raises if it isn't from Nifty

To check the signature yourself, use the Base64 after whsec_ in the secret as the key. Compute the HMAC-SHA256 of {webhook-id}.{webhook-timestamp}.{body}, and compare its Base64 with the part after v1, in constant time. Refuse timestamps that are more than a few minutes old.

If you've lost the secret, choose New secret… on the webhook's page. The old secret stops working immediately.