Webhooks

Overview

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

How delivery works

1. When a credential or proof request reaches a qualifying status, the system queues a notification.

2. Once the status change is saved, the system immediately attempts delivery.

3. If the attempt fails and retries are configured, the notification is rescheduled. Rescheduled notifications are delivered when the WEBHOOK_NOTIFY task runs.

Schedule the task whenever you use webhooks (see Schedule the task). Besides handling retries, it delivers any notification whose first attempt was interrupted, for example by a restart.

Setting up webhooks

1. Reference a webhook task instance

Webhooks use a WEBHOOK_NOTIFY task instance for their settings. If you are using the base config, it includes the following instance, which you can reference as is:

task:
  WEBHOOK_NOTIFY:           # Instance name
    type: "WEBHOOK_NOTIFY"
    display: "task.webhookNotify"
    order: 5
    params:
      private:
        requestTimeoutSeconds: 30 # Time the system waits for delivery before treating the attempt as failed
        retries:                  # See Retries
          intervalSeconds: 1
          maxAttempts: 5
          exponentialFactor: 2.5

note

Verify your own configuration before relying on this sample.

With these settings, notifications can go to any host over https or mqtts, and failed attempts are retried.

To change the settings, adjust this instance or configure your own and reference it by its name. The following optional parameters restrict hosts and allow plain transports:

params:
  public:
    allowedHosts:
      - foo.com
      - "*.bar.ch"
      - 111.222.33.44
    allowInsecureHttpTransport: true

• allowedHosts supports exact domains, wildcard subdomains, and IP addresses. If omitted, all hosts are permitted. For MQTT, the broker's host must be in this list.
• allowInsecureHttpTransport allows plain http and mqtt; https and mqtts are always allowed. See Plain http and mqtt.
• requestTimeoutSeconds applies to both transports. For MQTT, it covers connecting to the broker and receiving the PUBACK.

2. Add webhooks to an exchange protocol

Set the webhookTask parameter on any OpenID4VC issuance or verification protocol, referencing the task instance by name:

issuanceProtocol:
  OPENID4VCI_FINAL1:
    params:
      public:
        webhookTask: "WEBHOOK_NOTIFY" # References a configured task instance

3. Pass the webhook URL or MQTT topic

When creating a credential or proof request with that protocol, include your webhook destination in the request body using the webhookDestinationUrl parameter:

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

For MQTT, use the structure mqtt(s)://[user:password@]host[:port]/topic. The default ports are 1883 for mqtt and 8883 for mqtts. The topic can have several segments, for example /org/events/credential.

4. Schedule the task

Run the WEBHOOK_NOTIFY task on a schedule; Procivis One does not run it automatically. See Tasks.

Each run processes only notifications created through the named instance. The response lists the IDs of notifications processed in that run under delivered, failed, and rescheduled.

Notifications

Notification events

The system sends a notification when a credential or proof request reaches one of the following statuses.

Credential status changes:

• ACCEPTED
• SUSPENDED
• REVOKED
• REJECTED
• ERROR

Proof request status changes:

• ACCEPTED
• REJECTED
• ERROR

Payload

For HTTP, the system sends a POST request with Content-Type: application/json. For MQTT, it publishes the same body to the topic.

{
  "credentialId": "UUID",     // Credential notifications only
  "proofId": "UUID",          // Proof request notifications only
  "status": "string",         // New status
  "eventTimestamp": "string"  // Time of the status change, RFC 3339
}

eventTimestamp is set when the notification is queued and does not change on retries, so you can use it to order events.

Response handling

The system records the final outcome of each notification in history (entityType: NOTIFICATION). Attempts that are rescheduled are not recorded. If you are implementing the receiving endpoint, respond as follows.

Result	Outcome
HTTP 2xx or MQTT PUBACK	Delivered.
HTTP 404 or 5xx, no response within requestTimeoutSeconds, or connection failure	Rescheduled if retries are configured and attempts remain; otherwise error.
Other HTTP 3xx or 4xx	Error. Never retried.

Retries

The retries parameters control how failed attempts are retried. Without retries, the first failed attempt is final: the notification is recorded as an error and is not sent again.

params:
  private:
    retries:
      intervalSeconds: 1      # Delay before the first retry
      maxAttempts: 5          # Total attempts, including the first
      exponentialFactor: 2.5  # Multiplies the delay after each retry

Each retry becomes due intervalSeconds × exponentialFactor^n after the previous scheduled attempt, where n is the number of retries so far. With the values above, the retries become due 1, 2.5, 6.25, and 15.6 seconds after the previous attempt.

Retries are performed by the task, not on a timer: a due retry is attempted at the next task run. How frequently you run the task therefore sets the effective minimum interval. For example, with the values above and the task running once per minute, each retry happens at the next run.

Once maxAttempts is reached, the system prints a warning to logs and records the error in history.

Plain http and mqtt

https and mqtts destinations are always allowed. To allow plain destinations:

• mqtt — set allowInsecureHttpTransport: true on the task instance.
• http — set allowInsecureHttpTransport: true on the task instance and globalSettings.httpClient.insecureHttpTransportAllowed: true in the Core configuration. The httpClient setting allows plain http for all outbound requests from the Core, not only webhooks.