Webhooks

In this guide, we will look at how to register and consume webhooks. With webhooks, your app can know when something happens in SBL Express, such as someone sending a message or adding a contact.

Registering webhooks

Webhooks are at the moment sent with create requests in the API. In the future this will manageble in the admin dashboard. Now, whenever something of interest happens in your app, a webhook is fired off by Stacc SBL. In the next section, we'll look at how to consume webhooks.

Consuming webhooks

When your app receives a webhook request from SBL Express, check the type attribute to see what event caused it. The first part of the event type will tell you the payload type.

In the future the payload will align with the CloudEvents standard. Backwards compatibility will be maintained.

Example webhook payload

{
  "webhookId": "a056V7R7NmNRjl70",
  "type": "consent.created", // Deprecated, use event instead
  "event": "consent.created",
  "timestamp": "2025-01-16T00:00:00.000Z", // ISO 8601 timestamp
  "payload": {
    "externalId": "12345678903", // Defined at the start of the flow
    "flow": "0123456789abcdef",
    "nationalId": "12345678903",
    "authorizationCode": "altinnsuniqueidentifier"
  }
}

In the example above, a conversation was updated, and the payload type is a conversation.

See all event types

Event types

Name
consent.created
Description
A new consent request was created.
Name
consent.accepted
Description
Consent was accepted by the user
Name
consent.rejected
Description
Consent was rejected by the user
Name
consent.deleted
Description
Called when a consent is deleted. Initiated only through the usage of deletion in the API (DELETE /api/flows/:flowId)
Name
consent.data
Description
Contains the data. This is preceded by a consent.accepted event
Name
consent.timedOut
Description
When a accepted consent is no longer valid.
Name
consent.timedOutDataFailed
Description
When a accepted consent is no longer valid and the data could not be fetched.
Name
user.timedOut
Description
When the user does not respond to a consent request within about 10 days.
Name
tax.dataFailed
Description
When the tax data could not be fetched.
Name
income.dataFailed
Description
When the income data could not be fetched.

Consent rejected

{
    "webhookId": "a056V7R7NmNRjl70",
    "type": "consent.rejected",
    "payload": {
        "flow": "0123456789abcdef",
        "nationalId": "12345678903"
    }
}

Consent deleted

{
    "webhookId": "a056V7R7NmNRjl70",
    "type": "consent.deleted",
    "payload": {
        "flow": "0123456789abcdef",
        "nationalId": "12345678903"
    }
}

Security

To know for sure that a webhook was, in fact, sent by Stacc SBL instead of a malicious actor, you can verify the request signature. Each webhook request contains a header named x-stacc-sbl-signature, and you can verify this signature by using your secret webhook key. The signature is an HMAC hash of the request payload hashed using your secret key. Here is an example of how to verify the signature in your app:

Verifying a request

const signature = req.headers['x-stacc-sbl-signature']
const hash = crypto.createHmac('sha256', secret).update(payload).digest('hex')

if (hash === signature) {
  // Request is verified
} else {
  // Request could not be verified
}

If your generated signature matches the x-stacc-sbl-signature header, you can be sure that the request was truly coming from Stacc. It's essential to keep your secret webhook key safe — otherwise, you can no longer be sure that a given webhook was sent by Stacc. Don't commit your secret webhook key to git!