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

Customer Controls

Control	Customer responsibility
Destination URL	Register an HTTPS endpoint owned by your application
Signature secret	Store it server-side and verify every delivery
Event selection	Subscribe only to events the application consumes
Idempotency	Deduplicate retries before applying side effects
Staging destination	Keep staging delivery isolated from production infrastructure

Inspect Hosted Staging


SPAPS_API_URL=https://api.sweetpotato.dev \
  SPAPS_API_KEY="$SPAPS_API_KEY" \
  npx spaps webhook list

Common Mistakes

Register only destinations you control. Sweet Potato may reject private, unsafe, or unapproved destinations even when the URL is syntactically valid.

Skipping signature validation because a webhook route is “internal”.
Retrying delivery without idempotency.
Sending production provider events during unit tests. Use deterministic fixtures there and explicitly scoped provider test events for staging integration checks.