Outbound events: a signed webhook notifier and more events than three #240

New issue

Closed

opened 2026-09-15 21:23:33 +00:00 by tiagoagueda · 0 comments

tiagoagueda commented

2026-09-15 21:23:33 +00:00

Owner

Integrations have to poll today. Found in the 2026-09-15 code audit.

Today

There are three events: reminder_due, capture_received and went_quiet (notifications/base.py:26-30).
There is no webhook notifier (grep for webhook finds nothing), so an automation (n8n, Home Assistant, a script) has to poll the API and diff.
The change feed on the API side (updated_since) is covered in the API issue (#230).

Proposal

A built-in Webhook notifier:
- POSTs JSON to a URL the person gives;
- signed with HMAC-SHA256 over a timestamp and the body, using a per-connection secret, in a Postulo-Signature header;
- delivered through the guarded client, with the same destination rules as any connection;
- retried with backoff through the task queue, and deduplicated by the notification's stable key (see the plugin-surface issue (#229)).
Payload: event, occurred_at, key, the human title and body, and structured data with ids and URLs (never the person's documents).
More events, each still switchable per connection:
- an application's status changed;
- an interview was scheduled or moved;
- a posting closes soon (see the deadlines issue (#238));
- an offer was recorded (see the offers issue (#237)).
The earlier rule still applies: tell people what happens to them, not what they did. So the status and interview events should default off for human-facing notifiers and on for the webhook notifier.
Docs: a wiki page with the payload schema, how to verify the signature, and a sample receiver.

Integrations have to poll today. Found in the 2026-09-15 code audit. ## Today - There are three events: `reminder_due`, `capture_received` and `went_quiet` (`notifications/base.py:26-30`). - There is no webhook notifier (grep for `webhook` finds nothing), so an automation (n8n, Home Assistant, a script) has to poll the API and diff. - The change feed on the API side (`updated_since`) is covered in the API issue (#230). ## Proposal - **A built-in *Webhook* notifier:** - `POST`s JSON to a URL the person gives; - signed with HMAC-SHA256 over a timestamp and the body, using a per-connection secret, in a `Postulo-Signature` header; - delivered through the guarded client, with the same destination rules as any connection; - retried with backoff through the task queue, and deduplicated by the notification's stable key (see the plugin-surface issue (#229)). - **Payload:** `event`, `occurred_at`, `key`, the human title and body, and structured `data` with ids and URLs (never the person's documents). - **More events**, each still switchable per connection: - an application's status changed; - an interview was scheduled or moved; - a posting closes soon (see the deadlines issue (#238)); - an offer was recorded (see the offers issue (#237)). The earlier rule still applies: tell people what happens *to* them, not what they did. So the status and interview events should default **off** for human-facing notifiers and **on** for the webhook notifier. - **Docs:** a wiki page with the payload schema, how to verify the signature, and a sample receiver.

tiagoagueda added the

enhancement

label

2026-09-15 21:23:33 +00:00

tiagoagueda referenced this issue

2026-09-15 21:24:47 +00:00

The API: pages built after loading everything, an unpaginated /captures, captures that duplicate on retry, a public schema, no change feed #230

tiagoagueda added this to the 0.5.0 milestone

2026-09-15 21:33:32 +00:00

tiagoagueda referenced this issue from a commit

2026-09-16 12:02:00 +00:00

Build a page of the API from one page, and stop a retry making a second capture