Skip to main content

Webhooks

This guide will demonstrate how to create or manage a webhook using Sovrin.

Prerequisites​

You need the following in order to proceed with this tutorial:

  • Access to the Sovrin APIs

  • A Sovrin API flow set that utilises a webhook event type

If you’re experiencing any difficulties, contact us.

Create a webhook​

Request​


POST https://api.sovrin.one/v1/webhooks


{
    "events": [
        "{{event_type}}"
    ],
    "url": "https://example.com"
}

In the events array, the allowed types are OpenIdCredentialIssued or OidcIssuerCredentialIssued.

The webhook event is triggered by the Sovrin platform and allows users to subscribe to events that occur during supported Sovrin operations.

The following webhook events are currently supported on Sovrin:

  • OpenIdCredentialIssued - This webhook event is triggered when a credential is issued using OpenID Credential Provisioning flow.

  • OidcIssuerCredentialIssued - This webhook event is triggered when a credential is issued via the Sovrin OIDC bridge

The url attribute in the request payload above is the URL that you want to set up to receive the webhook events when they are triggered by Sovrin for the specified events:

  • Must be a valid URL.

  • Must use the HTTPS protocol.

  • Must not be an IP address.

  • Must not include query parameters or has fragments.

  • Non-ASCII characters are normalised.

  • Must return a 2xx response, otherwise it will go through a retry cycle and eventually fail.

Response​


`{
    "id": "0c099611-19c4-4f29-8724-6b9e5ba1ef7c",
    "events": [
        "{{event_type}}"
    ],
    "url": "https://example.com",
    "disabled": false
}
`

In the events array, the allowed types are OpenIdCredentialIssued or OidcIssuerCredentialIssued.

When a webhook is created, the disabled property is set to false by default.

If you need to create the webhook in an initial state of disabled, you can override the default by supplying "disabled":true in the request body.

tip

When a webhook event is generated:

The Sovrin platform does not guarantee the delivery of events in the exact order that they are generated or that no duplicate events will be received by the webhook endpoint.

Sovrin users can safeguard against duplicates by checking the event.id that is provided in the event payload, this is a unique identifier for each event generated by Sovrin. Alternatively, by making your event processing idempotent.

Disable a webhook​

Existing webhooks can be disabled by updating the webhook.

When a webhook is disabled, notifications for the events associated with this webhook will be not sent.

Request​


PUT https://api.sovrin.one/v1/webhooks/<WebhookID>


{
    "events": [
        "{{event_type}}"
    ],
    "url": "https://example.com",
    "disabled": true
}

In the events array, the allowed types are OpenIdCredentialIssued or OidcIssuerCredentialIssued.

Response​


{
    "id": "0c099611-19c4-4f29-8724-6b9e5ba1ef7c",
    "events": [
        "{{event_type}}"
    ],
    "url": "https://example.com",
    "disabled": true
}

In the events array, the allowed types are OpenIdCredentialIssued or OidcIssuerCredentialIssued.

Timeout and retry​

When a webhook fails to send data to the desired notification URL or a session timeout occurs, a maximum of 3 retry attempts are made by Sovrin at set intervals.

The interval time increases exponentially according to the number of retries that have been attempted.

If the webhook fails to send following the retry attempts, it will be marked as failed.

By default, the Sovrin webhook service has a response timeout of 3 seconds. This means if the server receiving the webhook event does not respond within this period it is considered a failure.