Operator surface

Knocker’s operator actions are durable SQLite operations exposed through the language bindings. It is not a built-in HTTP control plane.

For production recovery recipes, see the Operator runbook.

Common Operations

Python

events = webhooks.list_events(endpoint="stripe", limit=50)
invalid = webhooks.list_deliveries(
    endpoint="stripe",
    signature_valid=False,
    orphaned=True,
    since=1700000000,
    limit=50,
)

event = webhooks.get_event(42)
delivery = webhooks.get_delivery(99)

webhooks.ignore(event.id)
webhooks.replay(event.id)
webhooks.requeue(event.id)
webhooks.replay_delivery(delivery.id)

Raw SQL

SELECT e.id, ep.name AS endpoint, e.event_type, e.status, e.last_error
FROM knocker_events e
JOIN knocker_endpoints ep ON ep.id = e.endpoint_id
ORDER BY e.id DESC
LIMIT 50;

SELECT d.id, d.event_id, ep.name AS endpoint, d.signature_valid, d.signature_error
FROM knocker_deliveries d
JOIN knocker_endpoints ep ON ep.id = d.endpoint_id
WHERE ep.name = 'stripe'
  AND d.signature_valid = 0
ORDER BY d.received_at DESC
LIMIT 50;

SELECT knocker_mark_ignored(:event_id, 0);
SELECT knocker_replay(:event_id, 'knocker.events', 3);
SELECT knocker_requeue(:event_id, 'knocker.events', 3);

-- replay_delivery is a binding helper over a selected delivery body:
-- reset the event, clear stale live jobs for that event, then enqueue
-- {"event_id": ..., "delivery_id": ...} with honker_enqueue(...).

Bun

const events = webhooks.listEvents(50);
const invalid = webhooks.listDeliveries({
  endpoint: "stripe",
  signatureValid: false,
  orphaned: true,
  since: 1700000000,
  limit: 50,
});

const event = webhooks.getEvent(42);
const delivery = webhooks.getDelivery(99);

webhooks.ignore(event.id);
webhooks.replay(event.id);
webhooks.requeue(event.id);
webhooks.replayDelivery(delivery.id);

Elixir

{:ok, events} = KnockerSqlite.list_events(webhooks, 50)
{:ok, invalid} =
  KnockerSqlite.list_deliveries(webhooks, %{
    endpoint: "stripe",
    signature_valid: false,
    orphaned: true,
    since: 1_700_000_000,
    limit: 50
  })

{:ok, event} = KnockerSqlite.get_event(webhooks, 42)
{:ok, delivery} = KnockerSqlite.get_delivery(webhooks, 99)

{:ok, :ignored} = KnockerSqlite.ignore(webhooks, event["id"])
{:ok, _} = KnockerSqlite.replay(webhooks, event["id"])
{:ok, _} = KnockerSqlite.requeue(webhooks, event["id"])
{:ok, _} = KnockerSqlite.replay_delivery(webhooks, delivery["id"])

Go

events, err := webhooks.ListEvents(50)
if err != nil {
    return err
}

event, err := webhooks.GetEvent(42)
if err != nil {
    return err
}

delivery, err := webhooks.GetDelivery(99)
if err != nil {
    return err
}

_ = webhooks.Ignore(event.ID)
_ = webhooks.Replay(event.ID)
_ = webhooks.Requeue(event.ID)
_ = webhooks.ReplayDelivery(delivery.ID)

Node

const event = webhooks.getEvent(42);
const delivery = webhooks.getDelivery(99);
const related = webhooks.listDeliveriesForEvent(event.id);
const invalid = webhooks.listDeliveries({
  endpoint: "stripe",
  signatureValid: false,
  orphaned: true,
  since: 1700000000,
  limit: 50,
});

webhooks.ignore(event.id);
webhooks.replay(event.id);
webhooks.requeue(event.id);
webhooks.replayDelivery(delivery.id);

Ruby

events = webhooks.list_events(limit: 50)
invalid = webhooks.list_deliveries(
  endpoint: "stripe",
  signature_valid: false,
  orphaned: true,
  since: 1_700_000_000,
  limit: 50,
)

event = webhooks.get_event(42)
delivery = webhooks.get_delivery(99)

webhooks.ignore(event["id"])
webhooks.replay(event["id"])
webhooks.requeue(event["id"])
webhooks.replay_delivery(delivery["id"])

Semantics

Event lists are newest-first, inclusive on since, and bounded. Delivery reads preserve receipt-level audit/debugging details, including invalid and orphaned receipts.

Current action semantics:

• ignore(...) is allowed from received, failed, or dead.
• ignore(...) is a no-op when the event is already ignored.
• replay(...) is allowed from handled, failed, dead, or ignored.
• requeue(...) is allowed from failed, dead, or ignored.
• replay(...) and requeue(...) use the canonical Event payload.
• replay_delivery(...) is explicit and delivery-level: it processes the specified stored Delivery body through the linked event’s handler without mutating the canonical Event payload.

Provider redelivery of a dead event is audit-only. Knocker stores the new Delivery, keeps duplicate ingest non-mutating, and waits for an operator to call requeue(...) or replay_delivery(...).

Concurrency Model

Operator reads are best-effort under concurrent worker activity. They are good for inspection and manual recovery, but they are not advertised as a cross-call snapshot API.