Prompt
I'm building a webhook listener for Stripe and GitHub — how should I structure it?
Latest observation
A good webhook listener for Stripe and GitHub should be designed around a few core principles:
- Verify authenticity
- Respond fast
- Make handlers idempotent
- Decouple receipt from processing
- Log and replay safely
Here’s a practical structure you can use.
1) Put each provider behind its own endpoint
Don’t try to use one “generic webhook” without provider-specific verification.
Example:
POST /webhooks/stripePOST /webhooks/github
Why:
- Stripe and GitHub sign payloads differently
- Retry behavior differs
- Event schemas differ
- It’s easier to maintain and secure
2) Verify signatures before doing anything else
Stripe
- Use the raw request body
- Verify with the Stripe signing secret
- Reject if signature verification fails
GitHub
- Verify
X-Hub-Signature-256using your webhook secret - Also use the raw request body
Important:
- Don’t parse and reserialize JSON before verification
- Use the exact raw bytes received
3) Keep the webhook handler very thin
Your webhook endpoint should do only:
- Read raw body
- Verify signature
- Parse event
- Persist the event record
- Enqueue async processing
- Return
2xxquickly
Do not perform heavy work in the request thread:
- no database migrations
- no API fanout
- no long-running business logic
- no retries inside the HTTP request if possible
4) Use an internal event pipeline
A solid pattern is:
Webhook request → verified event → durable queue/db → worker → business logic
Why this helps
- Stripe/GitHub will retry if you time out
- async workers can retry with backoff
- you can safely inspect and replay failed events
- you avoid duplicate processing from retries
Minimal flow
- Store raw event payload
- Store provider event ID
- Mark status:
received,processing,processed,failed - Worker consumes from queue or DB table
5) Make processing idempotent
Both Stripe and GitHub can deliver the same event more than once.
Use provider event IDs as dedupe keys:
- Stripe:
event.id - GitHub:
X-GitHub-Deliveryheader is usually the delivery UUID; payload also has useful IDs depending on event type
Recommended approach
Before processing:
- check whether this event/delivery ID has already been handled
- if yes, no-op and return success
Also make your business actions idempotent:
- “create invoice” should not create duplicates
- “add user to org” should tolerate repeats
- “mark PR merged” should be safe if repeated
6) Use a DB table for event tracking
A simple table works well.
Example schema
webhook_events
- id
- provider -- 'stripe' | 'github'
- provider_event_id
- event_type
- delivery_id -- especially for GitHub
- payload_json
- signature_valid -- boolean
- status -- received | queued | processing | processed | failed
- error_message
- received_at
- processed_at
Add unique constraints like:
(provider, provider_event_id)unique- maybe
(provider, delivery_id)unique for GitHub deliveries
This prevents duplicate inserts on retries.
7) Separate routing from business logic
Don’t put all logic in the HTTP controller.
Structure like:
/webhooks
stripe_handler
github_handler
/services
stripe_event_service
github_event_service
/workers
process_webhook_event
/domain
billing
repo_sync
notifications
Handler responsibilities
- authenticate
- validate shape
- persist
- queue
Service/worker responsibilities
- interpret event types
- call internal domain functions
- handle retries and failure states
8) Handle provider-specific event types explicitly
Avoid a giant “if/else” blob in one file. Use event dispatch maps.
Stripe example
checkout.session.completedinvoice.paidcustomer.subscription.updated
GitHub example
pushpull_requestissue_commentinstallation
Use a dispatcher:
- event type → handler function
- unknown events → log and safely ignore
9) Return correct HTTP responses
- Return
200or204when the event is accepted - Return
400for malformed payloads - Return
401/403for failed signature verification - Return
500only for real server errors
If verification fails, fail fast. If processing fails after enqueueing, the webhook endpoint should still usually return success if the event is durably stored.
10) Build for retries and replay
Both providers retry on failure/timeouts.
Your system should support:
- replaying failed events
- manually reprocessing one event
- dead-lettering repeated failures
- inspecting payloads in admin tooling or logs
This is especially useful when you deploy a bug and need to re-run old events.
11) Be careful with ordering assumptions
Don’t assume webhooks arrive in order.
Examples:
- Stripe event A may arrive after event B
- GitHub push events can arrive close together and out of order
So:
- always fetch current state from the provider if needed
- reconcile by ID, not by event order
- make updates conditional
12) Secure the endpoint beyond signatures
Additional good practices:
- HTTPS only
- restrict endpoint exposure where possible
- rotate secrets regularly
- log minimal sensitive payload data
- rate limit abusive traffic
- monitor failed signature attempts
If you’re behind a reverse proxy, preserve the raw body correctly.
13) Good reference architecture
Simple version
If you’re small/early stage:
- Web server verifies signature
- Inserts event into database
- Background worker polls the table
- Worker processes and marks status
More scalable version
- Web server verifies signature
- Pushes to queue (SQS, RabbitMQ, Redis queue, Kafka, etc.)
- Worker consumes queue
- Persistent event store for auditing/replay
14) Suggested implementation pattern
Request path
- Receive webhook
- Capture raw body
- Verify signature
- Extract event ID + type
- Insert into
webhook_eventsif not exists - Queue job with event record ID
- Return
200
Worker path
- Load event from DB
- Check if already processed
- Dispatch by provider/type
- Run idempotent business action
- Mark processed or failed
15) Practical tips for Stripe and GitHub specifically
Stripe
- Use official SDK verification helpers
- You often need to handle lifecycle events and internal object updates
- Consider fetching the latest Stripe object if event data is incomplete
GitHub
- Watch for installation-related events if you’re building a GitHub App
- Use delivery ID dedupe
- Some events are noisy; only enable the ones you need
- For PR/repo state, you may want to re-fetch from GitHub to confirm current state
A simple mental model
Think of webhooks as:
“An untrusted notification that something may have happened.”
Not:
“A complete source of truth.”
Your app should verify, record, and reconcile.
If you want, I can also give you:
- a reference folder structure,
- a Node/Express example,
- a Python/FastAPI example, or
- a database schema + queue worker design for production use.