Skip to content

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.

Requirements for your webhook URL

  • Must be publicly accessible from the internet via HTTPS
  • Must accept both POST and OPTIONS requests

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:
Header Value
WebHook-Allowed-Origin Same value as WebHook-Request-Origin or *
WebHook-Allowed-Rate * (no rate limit) or a positive integer (requests per minute)
Code example (Kotlin/Ktor) 
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:

Status Code Result
200, 201, 202, 203, 204 Success - event delivered
400, 401, 403, 404, 413 Failure - no retry
Other codes Failure - retry with exponential backoff

4. Handle CloudEvents

Events are delivered in the CloudEvents 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 ...
  }
}

Always check the event type

Always verify the type field before processing the event. This ensures your system can handle new event types gracefully when they are introduced.

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:

Parameter Value
JWT Issuer https://login.microsoftonline.com/08a02467-3604-46e9-b818-6be676cf015b/v2.0
JWK URL https://login.microsoftonline.com/08a02467-3604-46e9-b818-6be676cf015b/discovery/v2.0/keys

Audience claim

Make sure to also verify the aud (audience) claim in the JWT.

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: