Webhook Implementation Guidelines#

This page provides guidelines for implementing a robust webhook to receive events from BankID Antifraud.

Store and process#

To ensure reliable event handling, we recommend implementing a store and process pattern. This approach separates the receiving of events from processing them, preventing downstream errors from affecting event delivery.

flowchart LR
    EG[Azure Event Grid] -->|POST| WH[Webhook]
    WH -->|Store| DB[(Event Store)]
    WH -->|HTTP 200| EG
    DB -->|Process| P[Processing Logic]

How it works#

1. 1
   Receive

   Your webhook receives the event from Azure Event Grid

2. 2
   Store

   Immediately persist the event to a durable store (database, queue, etc.)

3. 3
   Acknowledge

   Return HTTP 200 to confirm delivery

4. 4
   Process

   A separate process reads from the store and handles the event

Benefits#

• Decoupled delivery and processing: Downstream failures don't cause delivery retries
• Retry resilience: If processing fails, you can retry from your own store
• Auditability: All received events are persisted for later review
• Backpressure handling: Processing can happen at its own pace

Idempotency#

In the event of certain network issues, an event may be delivered more than once. Always use the event source + id field to ensure idempotent processing. This can be achieved either by checking the event against your event store before processing, or making sure all processing steps are idempotent.