Webhook Ingestion Blueprint

Receive and process incoming webhooks from external services with signature verification (HMAC/RSA), replay protection, idempotent deduplication, and async handler routing

   
Feature webhook-ingestion
Category Integration
Version 1.0.0
Tags webhooks, ingestion, signature-verification, replay-protection, events
YAML Source View on GitHub
JSON API webhook-ingestion.json

Fields

Name Type Required Label Description
source text Yes Webhook source identifier (e.g., provider name or integration ID)  
event_type text Yes Event type from the external service (e.g., payment.completed)  
payload json Yes Raw webhook payload body  
signature text Yes Cryptographic signature from the webhook header  
signature_algorithm select No Signature verification algorithm  
timestamp datetime Yes Webhook timestamp from the provider header  
event_id text Yes Unique event identifier for idempotency deduplication  
processing_status select No Current processing status  
handler_id text No Registered handler that processes this event type  
retry_count number No Number of handler retry attempts  
webhook_secret hidden Yes Shared secret or public key for signature verification  

Rules

  • signature_verification: Every incoming webhook must include a cryptographic signature in the request header, HMAC-SHA256: compute HMAC of raw body using shared secret; compare with provided signature, RSA-SHA256: verify signature using provider’s public key against raw body, Reject webhook immediately if signature does not match (do not process payload), Use constant-time comparison to prevent timing attacks on signature verification
  • replay_protection: Reject webhooks with timestamp older than 5 minutes from current server time, Clock skew tolerance of 30 seconds to account for network delays, Store processed event_ids for deduplication window (minimum 24 hours)
  • idempotency: Deduplicate by event_id; if event_id already processed, return 200 without re-processing, Deduplication window is 24 hours; events older than 24 hours may be reprocessed
  • processing: Store raw payload before processing (audit trail and replay capability), Route events to registered handlers based on source + event_type combination, Process handlers asynchronously; return 200 immediately to webhook sender, Failed handlers retry 3 times with exponential backoff (1s, 4s, 16s)
  • response: Always return 200 status to webhook sender after signature verification, Return 401 for invalid signatures; return 400 for malformed payloads, Provider will retry on non-2xx responses; avoid unnecessary retries by responding quickly

Outcomes

Webhook_received_and_verified (Priority: 1)

Given:

  • signature (request) exists
  • timestamp (request) exists
  • event_id (request) exists
  • Signature verification passes against raw payload
  • Timestamp is within 5-minute replay window

Then:

  • create_record
  • set_field target: processing_status value: verified
  • emit_event event: webhook.received
  • emit_event event: webhook.verified

Result: Webhook stored and verified; 200 returned to sender; async processing initiated

Webhook_processed_successfully (Priority: 2)

Given:

  • processing_status (db) eq verified
  • Handler registered for source + event_type combination
  • Handler executes without error

Then:

  • set_field target: processing_status value: completed
  • emit_event event: webhook.processed

Result: Webhook event processed by registered handler; status marked completed

Webhook_handler_failed_with_retry (Priority: 3)

Given:

  • processing_status (db) in verified,processing
  • Handler throws an error during processing
  • retry_count (db) lt 3

Then:

  • set_field target: retry_count value: retry_count + 1
  • set_field target: processing_status value: processing

Result: Handler retried with exponential backoff; retry count incremented

Webhook_handler_failed_permanently (Priority: 4) — Error: WEBHOOK_HANDLER_FAILED

Given:

  • retry_count (db) gte 3

Then:

  • set_field target: processing_status value: failed
  • emit_event event: webhook.failed

Result: Handler exhausted all retries; webhook marked as failed for manual investigation

Webhook_signature_invalid (Priority: 5) — Error: WEBHOOK_SIGNATURE_INVALID

Given:

  • Computed signature does not match provided signature

Then:

  • emit_event event: webhook.failed

Result: 401 returned; webhook rejected without storing or processing payload

Webhook_replay_detected (Priority: 6) — Error: WEBHOOK_REPLAY_DETECTED

Given:

  • Timestamp is older than 5 minutes from current server time

Then:

  • emit_event event: webhook.failed

Result: 400 returned; stale webhook rejected as potential replay attack

Webhook_duplicate_event (Priority: 7)

Given:

  • event_id already exists in processed events store

Result: 200 returned without re-processing; duplicate event silently ignored

Webhook_no_handler (Priority: 8) — Error: WEBHOOK_NO_HANDLER

Given:

  • No handler registered for the source + event_type combination

Then:

  • set_field target: processing_status value: completed
  • emit_event event: webhook.received

Result: Webhook stored for audit but no processing performed; 200 returned to sender

Errors

Code Status Message Retry
WEBHOOK_SIGNATURE_INVALID 401 Webhook signature verification failed. Payload may have been tampered with. No
WEBHOOK_REPLAY_DETECTED 400 Webhook timestamp is too old. Possible replay attack detected. No
WEBHOOK_HANDLER_FAILED 500 Webhook handler failed after all retry attempts. Manual investigation required. No
WEBHOOK_NO_HANDLER 400 No handler registered for this event type. Webhook stored but not processed. No
WEBHOOK_PAYLOAD_MALFORMED 400 Webhook payload could not be parsed. Expected valid JSON body. No

Events

Event Description Payload
webhook.received   source, event_type, event_id, timestamp
webhook.verified   source, event_type, event_id
webhook.processed   source, event_type, event_id, handler_id
webhook.failed   source, event_type, event_id, error_code, error_message
Feature Relationship Reason
payment-gateway recommended Receive payment status updates via provider webhooks
email-service optional Receive email delivery status notifications via webhooks
message-queue recommended Queue verified webhooks for async handler processing
api-gateway optional Route incoming webhooks through gateway for rate limiting