Skip to main content

Webhooks

Overview​

Set up the Core to send notifications of important issuance and verification events to a URL of your choosing.

Setting up webhooks​

1. Configure the webhook task provider​

Add a WEBHOOK_NOTIFY task to your configuration. The following example includes URL validation and configures the system to send one notification per qualified event:

task:
  WEBHOOK1:                 # Name the instance
    type: "WEBHOOK_NOTIFY"  # Required
    display: "task.webhookNotify"
    order: 5
    params:
      public:
        allowedHosts: # Optional — restricts which URLs the system will send notifications to
          - foo.com
          - *.bar.ch
          - 111.222.33.44
        allowInsecureHttpTransport: true # Optional
      private:
        requestTimeout: 30 # Seconds the system waits for a response before marking as error

allowedHosts supports exact domains, wildcard subdomains, and IP addresses. If omitted, all hosts are permitted.

2. Add webhooks to an exchange protocol​

Add the webhookTask parameter to any OpenID4VC issuance or verification protocol, specifying the task instance by name:

  OPENID4VCI_FINAL1:
    display: exchange.openid4vciFinal1
    order: 3
    type: "OPENID4VCI_FINAL1"
    params:
      public:
        webhookTask: "WEBHOOK1" # Optional — references the task instance name defined above

Any time you issue or verify with the protocol you will be able to specify a webhook URL for notifications.

Receiving notifications​

Pass the webhook URL​

When creating a credential or proof request, include your webhook URL in the request body using the webhookDestinationUrl parameter:

  • POST /api/credential/v1
  • POST /api/proof-request/v1

Notification events​

The system sends an HTTP POST request to your webhook URL when a credential or proof request reaches one of the following statuses.

Credential status changes:

  • ACCEPTED
  • SUSPENDED
  • REVOKED
  • ERROR

Proof request status changes:

  • ACCEPTED
  • REJECTED
  • ERROR

The request body has the following shape:

{
  "credentialId": "UUID",     // Present for credential notifications
  "proofId": "UUID",          // Present for proof request notifications
  "status": "string",         // New status (always present)
  "eventTimestamp": "string"  // Current time in RFC 3339 format (always present)
}

Response handling​

The system records delivery results in notification history (entityType: NOTIFICATION):

  • 2xx — delivery recorded as successful in history
  • 3xx / 4xx — warning printed to logs; error recorded in history
  • No response — system waits for the duration defined in requestTimeout; if still no response, marked as error (unless retries are configured, see below)
  • 404 / 5xx — if retries are configured (see below), the system will attempt redelivery

Advanced configuration​

Retries​

You can configure the system to retry failed notification attempts. Add retries to your task provider:

params:
  private:
    retries: # Optional
      interval: 1          # Minimum seconds between attempts
      maxAttempts: 5       # Total attempts before marking as permanently failed
      exponentialFactor: 2.5 # Multiplies the interval after each retry

Retries require that you call the task endpoint on a schedule (for example, a cron job). Because retries are triggered by this call rather than on a timer, attempts will occur no sooner than interval seconds after the previous failure, but the exact timing depends on how frequently you run the task.

To trigger the task manually or via a job:

POST /api/task/v1/run
{
  "name": "WEBHOOK1" // Reference the instance name
}

Once maxAttempts is exhausted, the system prints a warning to logs and records the final failure in history.