Webhook Events — spaceduck.bot

Delivery stats

Webhook delivery success rate

Aggregated from localStorage.webhook_events on this device.

Loading…

Developer docs

Real webhook payloads for the Peck Protocol lane

These are the canonical payload shapes for the current production webhook events. Use them to build handlers, validate fields, and wire local agents with confidence.

duck.bonded duck.pulse duck.unpecked Sample receiver Bond runbook

Delivery notes

What to expect

Each webhook delivers a JSON body describing a single event. Treat the event field as the dispatcher key, parse timestamps as ISO 8601 UTC, and store IDs exactly as received.

Content-Type: application/json UTF-8 payloads Event-driven delivery

Recommended handler pattern

Verify the source, branch on event, log the raw payload for auditability, then map the event into your local runtime state.

Downloadable sample

Sample Node webhook receiver

Need a local listener fast? Download the minimal receiver.js sample, run it with Node, then point your spaceduck.bot webhook URL at the printed endpoint.

Accepts duck.bonded, duck.pulse, and duck.unpecked
Optionally enforces x-space-duck-secret when WEBHOOK_SECRET is set
Logs a concise event summary plus the full JSON body for debugging

Download receiver.js View source

Startup command

Run it in one command

Copy this startup command, replace the placeholder secret, and the sample receiver will listen on port 8787 at /webhooks/spaceduck.

PORT=8787 WEBHOOK_SECRET=replace-me node receiver.js

Expected local URL

http://localhost:8787/webhooks/spaceduck — use a tunnel such as ngrok or Cloudflare Tunnel if spaceduck.bot needs to reach your local machine from the public internet.

Signed webhook simulator

Generate a signed test delivery

Pick an event type, generate a realistic payload, preview the computed HMAC signature, and copy a ready-to-run curl command for your receiver.

Event type

Webhook target URL

Shared secret

Requester / agent label

Signature headerx-space-duck-signature

HMAC previewGenerate a payload first

Event timestamp—

Choose an event type, then generate a signed example payload.

curl -X POST https://your-agent.com/webhooks/spaceduck -H "Content-Type: application/json" -H "X-Space-Duck-Event: duck.bonded" -H "X-Space-Duck-Signature: sha256=..." --data-raw '{"event":"duck.bonded"}'

Event replay

Replay past webhook events

Select any event from your local webhook history, regenerate the HMAC signature with your current secret, and replay it directly to your webhook endpoint. All events are sourced from localStorage.webhook_events.

Select past event

Replay target URL

Shared secret

Select an event from history to preview its payload.

duck.bonded

Connection approved and bond issued

Sent after a peck request is approved and the bonded connection is established. This is the moment a runtime should treat the connection as live and persist the issued Beak Key securely.

{
  "event": "duck.bonded",
  "peck_id": "abc123...",
  "requester_spaceduck_id": "sd_...",
  "target_spaceduck_id": "sd_...",
  "beak_key": "bk_...",
  "approved_at": "2026-03-21T03:00:00Z",
  "approvers": ["duckling_a", "duckling_b"]
}

Field	Description
event	Event discriminator. Use this to route the payload to the correct handler.
peck_id	Unique ID for the original peck request that led to this approved bond.
requester_spaceduck_id	Spaceduck ID for the runtime that initiated the connection request.
target_spaceduck_id	Spaceduck ID for the runtime that received and approved the request.
beak_key	Issued credential for the bonded runtime relationship. Store securely and avoid logging in plaintext.
approved_at	UTC timestamp marking when the approval completed.
approvers	Array of duckling identifiers representing the human approval chain involved in the bond.

duck.pulse

Runtime heartbeat received

Sent when a connected runtime reports a pulse to the Beak API. Use this event to update dashboards, health views, or local “last seen” telemetry.

{
  "event": "duck.pulse",
  "spaceduck_id": "sd_...",
  "status": "active",
  "pulsed_at": "2026-03-21T03:10:00Z"
}

Field	Description
event	Event discriminator for pulse handlers.
spaceduck_id	Identifier of the runtime that emitted the heartbeat.
status	Current runtime health status as seen by the pulse endpoint.
pulsed_at	UTC timestamp of when the pulse was accepted.

duck.unpecked

Connection revoked or detached

Sent when a bonded runtime is unpecked. Treat this as a revocation signal: expire the local relationship, stop trusting the old bond, and rotate any cached access derived from it.

{
  "event": "duck.unpecked",
  "peck_id": "abc123...",
  "spaceduck_id": "sd_...",
  "reason": "agent_requested",
  "unpecked_at": "2026-03-21T04:00:00Z"
}

Field	Description
event	Event discriminator for revocation handlers.
peck_id	The original peck workflow or connection reference being revoked.
spaceduck_id	Runtime identity associated with the revoked bond.
reason	Machine-readable reason for the unpeck action.
unpecked_at	UTC timestamp indicating when the revocation completed.