Technology · Discipline

Webhook ingestion and verification

Inbound vendor events are signature-checked, batched durably and delivered to the team that caused them, in the gateway and in the in-house social integrations.

FAFOHive gateway and social modulesHMAC-signed shared contractEdge listener
One inbound event
On the wire
verifystoreacknowledge
Event redelivery
may repeat
Payment or social action
never repeated
  • 300 sreplay window on every signed delivery
  • 6attempts at most, at widening intervals, on network and server errors only
  • 5 minbetween checks for events left unanswered past their deadline

Three rules in both event planes

FAFOHive receives webhooks in two event planes, and I set the same three rules for both: check the signature over the untouched body, store before acknowledging, and keep event redelivery separate from action repetition. Signatures are checked over raw bytes, because re-serialised JSON no longer matches. Events may be redelivered; payment and social actions are never repeated.

The bytes the vendor signed
as receivedsignature matches
The same event parsed and written back out
keys reordered, spacing changedsignature no longer matches

The platforms define their webhook formats; the receivers, the shared contract, the listener and the delivery semantics are mine. FAFO Core and Function Forge has a sibling platform that puts third-party APIs behind generic MCP servers, and webhook ingestion keeps its local copy of each vendor's data current between calls.

Business events to the team that caused them

The first plane carries business events from the payments, email/CRM and social-publishing providers that governed agent teams use. Each provider and environment has its own endpoint. The receiver checks the vendor's signature over the raw request body before parsing, stores the event, and only then answers success.

It finds the governed assignment that caused the event from the business objects that assignment created, freezes events into delivery batches with stable keys, and hands each batch to the owning team lead's mailbox once. An uncertain delivery is retried with the same batch and key. See Agents with real tools and no keys.

Events arrive
Frozen into a batch
First delivery
Retry, same batch and key
Team lead's mailbox
traced to the assignment that created the objectsuncertaindelivered once

Every mention answered

The second plane serves my X, Facebook and Reddit integrations, where the rule I was given was to answer every mention, comment and message. Each provider polls or receives platform activity, checks the platform's own webhook signatures (Meta's SHA-256 signature header and X's Activity webhook contract), stores events locally with deduplication by provider, kind and object, and mirrors them to a shared edge listener under one signed contract, whose replay window and dual secrets cover both attackers and key rotation.

Every delivery under the shared contract
  • HMAC over the exact body, timestampedreplay window
  • Secretsroom for two during rotation
  • Event identifierstable
  • Delivery identifierfresh per attempt
Retries, at widening intervals After a client error
one attempt, then nothing
A client error ends retries, because the receiver will reject the same request again.

The listener answers a duplicate as success without storing it twice, serves a signed pull feed, and on a timer raises a breach event for anything unanswered past its deadline. An agent answers an event by passing its identifier to the reply tool, which closes it.

An unanswered event escalates on a timer, so "answer every customer" is something the system checks.