Docs / Capability guide
Verified webhook inbox
Receive signed events and store each event once.
All capabilities · Related guide · Agent prompt for this capability
When to use this example
A creative approval or delivery alert may need to update another system. A receiver must handle retries and restarts without processing an unverified payload or storing the same delivery twice.
What the example gives you
The starter verifies signatures and writes accepted events to a durable SQLite inbox before acknowledging them. Its tests cover tampered payloads, expired signatures and duplicate deliveries. Your application supplies the code that acts on stored events.
Before you start
Python 3, a durable SQLite file, a signing secret in the environment and a public HTTPS reverse proxy for live delivery.
Run the example
Extract the archive and follow README.md for setup, commands, and expected results. Start with webhook_receiver.py. Local tests use sample data.
Python tools accept --help. To connect to your workspace, supply the deployment URLs, credentials and resource IDs required by the tool.
Connect it to your application
Start webhook_receiver.py locally and run its signed-request tests. It verifies HMAC over timestamp plus raw bytes, enforces a replay window and stores accepted events before acknowledging them.
Create a narrowly scoped webhook subscription pointing at your HTTPS receiver. Store the returned secret immediately in your secret store; never include it in URLs or logs.
Inspect failed deliveries and replay only after fixing the cause. During rotation accept the documented grace-period signatures, then remove the old secret. Process stored events idempotently by event ID.
Check the result
Unsigned, stale, oversized and tampered deliveries are rejected. A valid duplicate is acknowledged without adding another stored event, including after process restart.