Skip to content

Webhooks

Webhooks notify external systems when sync failures occur. They are the "alarm system" of the middleware.

How It Works

  1. A sync failure is reported via POST /api/v1/failures
  2. The FailureRegistryService determines the notification direction:
    • Failure source is Odoo -> webhook direction is to_webshop
    • Failure source is webshop -> webhook direction is to_odoo
  3. Active WebhookConfig entries matching the entity type and direction are looked up
  4. A WebhookDelivery is created for each matching config
  5. A DeliverWebhookMessage is dispatched to the messenger queue
  6. The handler sends an HTTP POST with the payload and an X-Webhook-Signature header (HMAC-SHA256)

Webhook Payload Example

{
  "event": "sync_failure",
  "entity_type": "product",
  "external_id": "PROD-001",
  "source": "webshop",
  "error_message": "Validation failed",
  "error_details": [{ "field": "price", "message": "Required" }],
  "failed_at": "2026-02-24T10:30:00Z"
}

Retry Strategy

Failed deliveries are retried with exponential backoff:

  • Attempt 1: immediate
  • Attempt 2: after 1 minute
  • Attempt 3: after 5 minutes
  • Attempt 4: after 30 minutes
  • Attempt 5: after 2 hours
  • Attempt 6: after 8 hours
  • Give up after 24 hours total

Configuration

Webhook endpoints are configured via the admin interface under Webhook Config. Each config specifies:

  • URL to deliver to
  • Entity type (product, partner, sale_order)
  • Direction (to_odoo, to_webshop)
  • Secret (for HMAC signing, stored encrypted)
  • Active/inactive status