propgate docs

CLI › webhooks

webhooks

Seven commands over the seven /v1/webhooks endpoints. See Webhook payloads for the event names and the shape that arrives at your endpoint.

webhooks create

propgate webhooks create \
  --url https://example.com/hooks/propgate \
  --events domain.failed,domain.recovered
Created.

  id       019fcf7a-2b3c-7d4e-9f5a-6b7c8d9e0f1a
  url      https://example.com/hooks/propgate
  events   domain.failed, domain.recovered
  state    enabled
  created  2026-08-06 09:12

  signing secret  whsec_7f3a9c2e1b8d4a6f0c5e2b9d7a4f1c8e

Shown once. Rotate with `propgate webhooks rotate <id>` if it is lost.

--url must be https and must not resolve to a private address; both are refused before the request is sent. --events takes any of domain.degraded, domain.failed, domain.recovered, domain.verified, comma-separated or repeated. Omit it and you get all four.

webhooks list and webhooks get

propgate webhooks list
enabled   https://example.com/hooks/propgate  domain.failed, domain.recovered
disabled  https://staging.example.com/hooks   all events

An empty events array means every event, and prints as all events rather than as a blank column.

webhooks update

propgate webhooks update <id> --state disabled
propgate webhooks update <id> --state enabled
propgate webhooks update <id> --events domain.verified

--state is one flag with three values — enabled, disabled, unchanged — rather than a --disable and an --enable. Two booleans for one two-valued thing lets a caller pass both, which needs a guard and an error message for a state that should never have been expressible; a select cannot contradict itself, and it is the shape a prompt wants anyway.

The API accepts a PATCH with an empty body and changes nothing. The CLI refuses one: reporting success for a request that did nothing is worse than saying which flag was missing.

webhooks rotate

propgate webhooks rotate <id> --window-hours 24
whsec_2d8f1a4c9e3b7f0a6c2e8d5b1f9a3c7e

Shown once. The previous secret keeps verifying until 2026-08-07 09:12, so deploy this one before then.

--window-hours is how long the previous secret keeps verifying, 0 to 168, defaulting to 24. A deploy is not instantaneous, and a rotation that invalidated the old secret the moment it ran would drop every signature in flight. --window-hours 0 expires it immediately, for the case where the old secret is the reason you are rotating.

webhooks deliveries

propgate webhooks deliveries <id> --status failed
propgate webhooks deliveries <id> --all --json
failed     domain.failed     2026-08-06 09:14  3 attempts  502 from endpoint
delivered  domain.degraded   2026-08-06 08:41  1 attempt
delivered  domain.verified   2026-08-05 17:02  1 attempt

--status filters to pending, delivered or failed. --all follows the cursor to the end rather than one page at a time; it asks for the server's maximum page size, so a full walk is one round trip per 200 rows. It is refused alongside --cursor, which says where to start.

Deliveries are recorded in Postgres, not in the queue — what is owed is never only in Redis. A flushed Redis costs in-flight attempts and no obligations, and this list is how you see that.

webhooks delete

Removes the endpoint. Nothing further is delivered to it, and nothing already queued is retried.