Ordering, versions, and schema evolution
Network delivery does not guarantee that related events arrive in the order they were created. Consumers should use timestamps, versions, and durable state transitions instead of assuming arrival order is business order.
Ignore or quarantine unsupported event types rather than treating them as a known event.
Route each schema_version to a compatible parser when version metadata exists.
Allow additive optional fields without breaking parsing, while still validating required fields.
Do not overwrite newer local state with an older event solely because it arrived later.
Keep contract tests for current and prior supported payload versions.
Test plan
Test
Expected result
Valid signed delivery
Verified, stored, queued, and acknowledged once.
Duplicate valid delivery
No duplicate business effect; successful acknowledgment.
Invalid signature
Rejected before payload processing.
Missing verification metadata
Rejected according to the active contract.
Old replay timestamp
Rejected outside allowed replay window.
Unknown event type
Safely ignored or quarantined with an operational signal.
Out-of-order related events
State remains correct and does not regress.
Temporary database outage before persistence
Retryable response according to contract.
Downstream outage after persistence
Callback succeeds; internal work retries.
Consumer timeout
No partial untracked business effect.
Secret rotation overlap
Deliveries signed with permitted current/previous keys
verify correctly.
Deleted subscription
No new deliveries expected after contract-defined
deactivation behavior.
Implementation examples
from flask import Flask, request, jsonify app = Flask( name )
@app.post("/webhooks/zahlen") def zahlen_webhook():
raw_body = request.get_data(cache=True)
metadata = read_contract_headers(request.headers)
if not verify_with_active_contract(raw_body, metadata): return jsonify({"accepted": False}), 401
envelope = parse_and_validate_contract_payload(raw_body) event_id = stable_event_id(envelope)
if inbox_already_completed(event_id):
return jsonify({"accepted": True, "duplicate": True}), 200
persist_and_enqueue_atomically(event_id, envelope, metadata) return jsonify({"accepted": True}), 200
Python callback skeleton
JavaScript callback skeleton
app.post("/webhooks/zahlen", rawBodyMiddleware, async (req, res) => { const rawBody = req.body;
const metadata = readContractHeaders(req.headers);
if (!verifyWithActiveContract(rawBody, metadata)) { return res.status(401).json({ accepted: false });
}
const envelope = parseAndValidateContractPayload(rawBody); const eventId = stableEventId(envelope);
if (await inboxAlreadyCompleted(eventId)) {
return res.status(200).json({ accepted: true, duplicate: true });
}
await persistAndEnqueueAtomically(eventId, envelope, metadata); return res.status(200).json({ accepted: true });
});