Receiving CloudEvents#

This page will help you set up your system to receive events from BankID Antifraud.

Integration steps#

1. Provide the required information#

Start by providing BankID with the full webhook URL where you want to receive the events.

2. Validate subscription#

When we create the subscription, a validation request will be sent to your URL via an HTTP OPTIONS call.

The request will include the header WebHook-Request-Origin containing a DNS expression identifying the sending system. This will be set to eventgrid.azure.net.

To accept the subscription, respond with:

• HTTP Status: 200
• Headers:

route("/bankid-antifraud-event") {
    options {
        call.response.headers.apply {
            append("WebHook-Allowed-Origin", "eventgrid.azure.net")
            append("WebHook-Allowed-Rate", "100")
            append(HttpHeaders.Allow, "POST")
        }
        call.respond(HttpStatusCode.OK)
    }
    authenticate("jwt") {
        post { handleAntifraudEvent() }
    }
}

3. Receive events#

Events are delivered as HTTP POST requests. For successful delivery, respond with one of the following status codes:

4. Handle CloudEvents#

Events are delivered in the CloudEvents⁠ (opens in a new tab) format. Here's an example request:

POST /your-subscription HTTP/1.1
Host: webhook.example.com
Content-Type: application/cloudevents+json; charset=utf-8
Content-Length: nnnn
Authorization: Bearer <token>

{
  "specversion": "1.0",
  "type": "no.bankid.antifraud.alarm.dispatch.v2",
  "source": "...",
  "id": "...",
  "time": "...",
  "data": {
    ... alarm data ...
  }
}

The domain-specific data (the alarm) will be in the data field.

5. Authenticate requests#

The service uses JSON Web Tokens (JWT) issued by Microsoft Entra ID to authorize requests. Each POST request includes a JWT in the Authorization header using the Bearer scheme.

Verify the token using:

Troubleshooting#

Subscription validation fails#

If the subscription validation fails, check the following:

• Firewalls are open for incoming requests
• The OPTIONS handler does not check the Authorization header (it will not be set during validation)
• Your endpoint accepts the Content-Type: application/cloudevents+json; charset=utf-8

Further documentation#

For more information about the underlying technologies, refer to:

• Azure Event Grid⁠ (opens in a new tab)
• Endpoint validation with Azure Event Grid⁠ (opens in a new tab)
• Event Grid CloudEvents Schema⁠ (opens in a new tab)
• Webhook delivery with Azure AD⁠ (opens in a new tab)