Webhooks And Event Delivery
SPAPS has two webhook jobs. It receives trusted provider events such as Stripe and Mailgun, and it delivers outbound events to registered downstream endpoints. Both directions need signing, idempotency, and destination governance because webhook bugs can become billing errors, email leaks, or SSRF risks.
Mental Model
Main Surfaces
| Surface | Location | Notes |
|---|---|---|
| Stripe webhooks | domains/stripe/webhook_handler.py | Signature validation, idempotent event dispatch, checkout/subscription/invoice handling |
| Mailgun webhooks | domains/webhooks/router.py, domains/webhooks/signing.py | Inbound signature verification and event ingestion |
| Outbound webhooks | domains/webhooks/delivery.py | HTTP delivery, retries, and signing |
| Destination governance | domains/webhooks/destination_security.py | Domain/IP checks to reduce SSRF and unsafe destinations |
Example Local Inspection
curl http://localhost:3301/health/ready
curl http://localhost:3301/api/metricsCommon Mistakes
Never accept arbitrary production webhook destinations without governance. Production startup checks require destination policy to be in an allowed posture.
- Skipping signature validation because a webhook route is “internal”.
- Retrying delivery without idempotency.
- Testing with real provider webhooks instead of deterministic mocked payloads.