Skip to main content
Consuming webhooks correctly ensures your systems stay in sync with Pocketsflow without losing events or duplicating work. This guide covers the main patterns to follow, regardless of your tech stack.

​
Core responsibilities

Your webhook endpoint should:
  1. Receive HTTP POST requests from Pocketsflow.
  2. Verify that each request is genuine using signatures.
  3. Parse the JSON payload.
  4. Process the event in an idempotent way (handle duplicates safely).
  5. Respond with a 2xx status code when processing succeeds.

​
Idempotency

Your code should be safe to run more than once with the same event. Typical approach:
  • Each event has a unique ID.
  • Before processing, check whether you’ve already seen that ID.
  • If yes, skip; if no, record it and proceed.
This protects you from:
  • Retries during transient errors.
  • Bugs that cause the same event to be delivered twice.

​
Handling retries

If your endpoint returns a non-2xx status or times out:
  • Pocketsflow may retry delivery for a period of time.
Best practices:
  • Keep your webhook handler fast—offload heavy work to background jobs or queues.
  • Return a 2xx status only after you’ve safely recorded the event.

​
Error handling

Plan for:
  • Invalid payloads.
  • Internal service outages.
  • Temporary connectivity issues.
Recommendations:
  • Log errors with enough context to debug later (event ID, type, and timestamp).
  • Consider monitoring or alerting when your error rate exceeds a threshold.

​
Example flow

Regardless of language, the pseudocode usually looks like:
  1. Read the raw request body.
  2. Verify the signature using your signing secret.
  3. Parse JSON into an event object.
  4. Check if the event’s ID has already been processed.
  5. If not:
    • Route based on event.type (for example, order.created, subscription.canceled).
    • Perform the relevant action (update database, send message, etc.).
    • Mark the event ID as processed.
  6. Return HTTP 200.
For concrete language examples, see Examples.