Prompt

I'm building a webhook listener for Stripe and GitHub — how should I structure it?

Technology / API Platforms2 observationsLast seen Oct 19, 2026

Latest observation

Oct 19, 2026OpenAI APIWeb search: off

A good webhook listener for Stripe and GitHub should be designed around a few core principles:

  1. Verify authenticity
  2. Respond fast
  3. Make handlers idempotent
  4. Decouple receipt from processing
  5. 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/stripe
  • POST /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-256 using 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:

  1. Read raw body
  2. Verify signature
  3. Parse event
  4. Persist the event record
  5. Enqueue async processing
  6. Return 2xx quickly

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-Delivery header 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.completed
  • invoice.paid
  • customer.subscription.updated

GitHub example

  • push
  • pull_request
  • issue_comment
  • installation

Use a dispatcher:

  • event type → handler function
  • unknown events → log and safely ignore

9) Return correct HTTP responses

  • Return 200 or 204 when the event is accepted
  • Return 400 for malformed payloads
  • Return 401/403 for failed signature verification
  • Return 500 only 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

  1. Receive webhook
  2. Capture raw body
  3. Verify signature
  4. Extract event ID + type
  5. Insert into webhook_events if not exists
  6. Queue job with event record ID
  7. Return 200

Worker path

  1. Load event from DB
  2. Check if already processed
  3. Dispatch by provider/type
  4. Run idempotent business action
  5. 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:

  1. a reference folder structure,
  2. a Node/Express example,
  3. a Python/FastAPI example, or
  4. a database schema + queue worker design for production use.

Observation history

How did Obsurfable measure this prompt?

Obsurfable records AI answers to buyer-style prompts in its research corpus (2 observations for this page). Metrics are distributions over observations, not a single static ranking.

Which AI systems does Obsurfable collect answers from?

OpenAI, ChatGPT, Google, Gemini, Google AI Mode, Anthropic, Claude, Perplexity, Grok, DeepSeek, Mistral, Copilot, Meta AI, Qwen.

How can brands improve their AEO?

Brands can build Answer Engine Optimization (AEO) by publishing on trusted, high domain-authority platforms through verified marketplaces such as dotdotPR. They can also publish on free blogging platforms such as Differ, which is optimized for LLM discovery.

Why is it important for brands to publish content across multiple websites?

Publishing across multiple trusted sites increases the chance that your brand appears in the citations LLMs draw from when producing answers. Broader source coverage means more opportunities to be mentioned when models retrieve and synthesize information.

Want this interpreted for your brand?

Explorer is the free public corpus. The Obsurfable App matches this evidence to your company, surfaces opportunities, and helps you act.