Repository navigation
Route Webhook
A payment provider, a library service or GitHub posts events to an address of yours. Route::webhook($route, $capability, $options) checks that the event comes from them (its signature), then calls a capability with it. There
is no session and no CSRF token: the signature is the only proof. Since 2.19.0.
Route::webhook('/stripe/events', 'record_event', ['verify' => 'stripe']); // STRIPE_WEBHOOK_SECRET=whsec_... in .env"Receive Stripe's checkout events at /stripe/events and record each one once."
Check before you say OK:
- the route has
verify, and the secret is the endpoint'swhsec_..., not the API key; - the capability starts by refusing every caller that is not the webhook (
$context->actorType() !== 'webhook'); - the same event posted twice is recorded once.
-
A table that remembers the events. Run
docker compose exec dev-box php caligrafer.php migrate make create_webhook_events, and write in the file it names:-- create_webhook_events CREATE TABLE IF NOT EXISTS webhook_events ( id INT UNSIGNED NOT NULL AUTO_INCREMENT, event_id VARCHAR(100) NOT NULL, type VARCHAR(100) NOT NULL, created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP, PRIMARY KEY (id), UNIQUE KEY uq_webhook_events_event_id (event_id) ) ENGINE = InnoDB DEFAULT CHARSET = utf8mb4;
Then
docker compose exec dev-box php caligrafer.php migrate. -
The capability.
docker compose exec dev-box php caligrafer.php service Bookshelf/RecordEvent, then makeapplication/services/Bookshelf/RecordEvent.phpread:<?php use Caligrafy\Capability; use Caligrafy\Context; use Caligrafy\Database; use Caligrafy\Service; use Caligrafy\ServiceError; #[Capability( name: 'record_event', description: 'Records an event that the library service posts (its id and type), once per event id.' )] class RecordEvent extends Service { public $rules = array('event' => 'required'); public function handle(array $input, Context $context) { // only the webhook route may record events: REST, MCP and pages would let a signed-in user make one up if ($context->actorType() !== 'webhook') { throw ServiceError::forbidden('Only the library service sends events'); } $event = $input['event']; if (!is_array($event) || empty($event['id']) || empty($event['type'])) { throw ServiceError::invalid(array('event' => 'The event needs an id and a type')); } // the sender posts an event again until it gets a 2xx: record each id once if (!Database::table('webhook_events')->where('event_id', $event['id'])->exists()) { Database::table('webhook_events')->insert(array('event_id' => $event['id'], 'type' => $event['type'])); } return array('recorded' => $event['id']); } }
-
The secret and the route. Add the secret the sender gave you to
.env(a placeholder here):LIBRARY_WEBHOOK_SECRET=whsec_test_library. Inweb.php, beforeRoute::run();:// the library service signs each event: X-Signature: sha256=<HMAC-SHA256 of the body with the secret> Route::webhook('/hooks/library', 'record_event', ['verify' => function ($rawBody, $headers) { $expected = 'sha256=' . hash_hmac('sha256', $rawBody, (string) getenv('LIBRARY_WEBHOOK_SECRET')); return hash_equals($expected, $headers['x-signature'] ?? ''); }]);
-
Post a signed event. Run:
BODY='{"id":"evt_1","type":"loan.returned"}' SIG="sha256=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac whsec_test_library -r | cut -d' ' -f1)" curl -s -i -X POST -H "Content-Type: application/json" -H "X-Signature: $SIG" http://localhost:8080/hooks/library -d "$BODY"
It answers
200with{"received":true}, andwebhook_eventshas one row. The same post again adds nothing. With-H "X-Signature: sha256=bad":400and{"error":{"code":"invalid_signature","message":"The signature is not valid"}}. AGETanswers405.
| Option | Default | What it does |
|---|---|---|
verify |
required |
'stripe', or function (string $rawBody, array $headers): bool (header names in lower case; only true passes) |
secret_env |
'STRIPE_WEBHOOK_SECRET' |
with 'stripe': the .env variable that holds the endpoint's signing secret (whsec_..., not the API key) |
secret |
none | with 'stripe': the secret itself, instead of the variable (tests) |
tolerance |
300 |
with 'stripe': how many seconds old a signature may be |
'stripe' checks the Stripe-Signature header with the Stripe library. Anything else is a function of yours, as in
step 3.
| The event | The answer |
|---|---|
| signature checked, capability done | 200 {"received": true} |
| bad or missing signature | 400 {"error":{"code":"invalid_signature",...}} |
| a body that is not JSON | 400 {"error":{"code":"invalid","message":"The body is not JSON"}} |
the capability refuses (ServiceError) |
its status and its error (422 for invalid) |
| no secret set, no such capability, an error in the capability |
500; the message goes to the PHP error log |
-
verifyis required: a webhook without it stops with an error whenweb.phpruns. - The body must be JSON; the capability gets
['event' => the decoded body], so declare$rules = ['event' => 'required']. - The capability runs as the system, with full access (
Context::system('webhook', $path); the audit log showswebhook /hooks/library): treat the event as data from outside. Before trusting an amount, ask the provider again (Stripe). - Webhook addresses skip the CSRF check that every other form post goes through.
Route::webhook()-
Caligrafy\Webhook:verify(),process()(a test posts an event without a server) Context::actorType()
-
'verify' => 'stripe'withoutSTRIPE_WEBHOOK_SECRET: every event answers500. Use the endpoint'swhsec_..., not thesk_...key. -
A webhook capability that is not idempotent: services post an event again until they get a
2xx, and a retried event is recorded twice. -
No
actorType()check: the capability is also served by REST, the JS client, MCP andphp caligrafer.php call, to anyone itsscopeandlevellet in, with an event they made up.
Caligrafy: Describe it. Approve it. Ship it. Your idea turned into a complete app: every feature built once, for web pages, Vue apps, a REST API and AI agents, and online.
Why Caligrafy: the benefits, the measurements, and what it is not yet
-
Quickstart with Claude: describe it, approve it, ship it
or the Quickstart: the same three steps by hand, in 5 minutes
- How Caligrafy works: the ideas in 5 minutes
- Your first capability: build a feature, page included
-
Capabilities in depth
-
#[Capability]: every option - Scheduled jobs: capabilities on a timer
- Notifications: web push and email
- Background jobs: capabilities run later
- Migrations: database changes, in order
- The cache
-
Testing your app
- Dependency injection
- Validation rules
-
Web pages
- Views and page components
- Design styles: another look, one setting
- Declarative routes: every request, in one line
-
Route::page·Route::form·Route::auth·Route::webhook·Route::download·Route::redirect·Route::action·Route::snap· capability routes - How to export a list as CSV
- Controllers: moving one to a declared route · how to, step by step
- Forms and helpers
-
Vue apps
-
Mobile and tablet
-
REST API
-
AI agents
-
Snap Cards and the assistant
- Payments: Stripe and crypto
- Face detection and face login
- OpenAI: chat and images · Assistants
- Open models: Llama, Mistral...
- Chatbots with Watson
- Machine learning in the browser
- Metadata and social cards · search and analytics
-
Putting it online: the production image, the database at every start
-
API reference: every class and method
-
Routing ·
Route·AuthRoutes· pages ·Controller· capabilities -
Data ·
Model·Query· sign-in · jobs ·Notify· payments · AI -
Interfaces · Snap ·
Snap\Cards·Snap\Conversation· testing · tooling · helper functions
-
Routing ·
-
Caligrafer: every command
- Project · build · data · agents · jobs and tests · maintenance · deploy
- Installation, configuration and Caligrafer
- Routing · Request · Controllers · Views
- Vue: flow of information · routes · validations
- Security and upgrading
- Release notes: 2.26 · 2.25 · 2.24 · 2.23 · 2.22 · 2.21 · 2.20 · 2.19 · 2.18 · 2.17 · 2.16 · 2.15 · 2.14 · 2.13 · 2.12 · 2.11 · 2.10 · 2.9 · 2.8 · 2.7 · 2.6 · 2.5 · 2.4 · 2.3 · 2.1 · October 2026 · changelog
- Testing Caligrafy (contributors)