Using Webhooks

Webhooks in Paradym provide a powerful way to listen to events that occur within Paradym. You create a webhook subscription with the URL of your endpoint and the events you want to receive, and Paradym sends every matching event to that URL as a webhook.

• Setting up a webhook subscription and your endpoint, including verifying the webhook signature.
• Retrieving and updating webhook subscriptions through the API.
• Timeouts and retries, with the delivery history and redelivery of webhooks.
• Webhook events: every event and its payload.

Setting up a webhook subscription

To start receiving webhooks, create a webhook subscription in the dashboard and set up your endpoint to verify every webhook it receives.

const crypto = require('node:crypto')
const express = require('express')
 
const SECRET = process.env.PARADYM_WEBHOOK_SECRET
 
const app = express()
 
// The signature covers the exact bytes that were sent, so use the raw body.
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = Buffer.from(req.get('X-Paradym-HMAC-SHA-256') ?? '')
  const digest = crypto.createHmac('sha256', SECRET).update(req.body).digest('hex')
  const expected = Buffer.from(digest)
 
  // Compare in constant time, so timing does not reveal the expected signature.
  if (
    signature.length !== expected.length ||
    !crypto.timingSafeEqual(signature, expected)
  ) {
    res.sendStatus(401)
    return
  }
 
  const webhook = JSON.parse(req.body.toString('utf8'))
  console.log(`Received ${webhook.eventType} (${webhook.webhookId})`)
 
  res.sendStatus(200)
})
 
app.listen(3000)

import hashlib
import hmac
import os
 
from flask import Flask, request
 
SECRET = os.environ["PARADYM_WEBHOOK_SECRET"].encode()
 
app = Flask(__name__)
 
 
@app.post("/webhook")
def webhook():
    # The signature covers the exact bytes that were sent, so use the raw body.
    body = request.get_data()
    signature = request.headers.get("X-Paradym-HMAC-SHA-256", "").encode()
    expected = hmac.new(SECRET, body, hashlib.sha256).hexdigest().encode()
 
    # Compare in constant time, so timing does not reveal the expected signature.
    if not hmac.compare_digest(signature, expected):
        return "", 401
 
    webhook = request.get_json()
    print(f"Received {webhook['eventType']} ({webhook['webhookId']})")
 
    return "", 200
 
 
if __name__ == "__main__":
    app.run(port=3000)

package main
 
import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"encoding/json"
	"io"
	"log"
	"net/http"
	"os"
)
 
var secret = []byte(os.Getenv("PARADYM_WEBHOOK_SECRET"))
 
func handleWebhook(w http.ResponseWriter, r *http.Request) {
	// The signature covers the exact bytes that were sent, so use the raw body.
	body, err := io.ReadAll(r.Body)
	if err != nil {
		w.WriteHeader(http.StatusBadRequest)
		return
	}
	signature := []byte(r.Header.Get("X-Paradym-HMAC-SHA-256"))
	mac := hmac.New(sha256.New, secret)
	mac.Write(body)
	expected := []byte(hex.EncodeToString(mac.Sum(nil)))
 
	// Compare in constant time, so timing does not reveal the expected signature.
	if !hmac.Equal(signature, expected) {
		w.WriteHeader(http.StatusUnauthorized)
		return
	}
 
	var webhook struct {
		WebhookID string `json:"webhookId"`
		EventType string `json:"eventType"`
	}
	if err := json.Unmarshal(body, &webhook); err != nil {
		w.WriteHeader(http.StatusBadRequest)
		return
	}
	log.Printf("Received %s (%s)", webhook.EventType, webhook.WebhookID)
 
	w.WriteHeader(http.StatusOK)
}
 
func main() {
	http.HandleFunc("POST /webhook", handleWebhook)
	log.Fatal(http.ListenAndServe(":3000", nil))
}

package example;
 
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.util.HexFormat;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestHeader;
import org.springframework.web.bind.annotation.RestController;
 
@SpringBootApplication
@RestController
public class WebhookApplication {
  private static final byte[] SECRET =
      System.getenv("PARADYM_WEBHOOK_SECRET").getBytes(StandardCharsets.UTF_8);
 
  // The signature covers the exact bytes that were sent, so use the raw body.
  @PostMapping("/webhook")
  public ResponseEntity<Void> webhook(
      @RequestHeader(name = "X-Paradym-HMAC-SHA-256", defaultValue = "")
          String header,
      @RequestBody byte[] body) throws Exception {
    byte[] signature = header.getBytes(StandardCharsets.UTF_8);
    Mac mac = Mac.getInstance("HmacSHA256");
    mac.init(new SecretKeySpec(SECRET, "HmacSHA256"));
    String digest = HexFormat.of().formatHex(mac.doFinal(body));
    byte[] expected = digest.getBytes(StandardCharsets.UTF_8);
 
    // Compare in constant time, so timing does not reveal the expected signature.
    if (!MessageDigest.isEqual(signature, expected)) {
      return ResponseEntity.status(401).build();
    }
 
    JsonNode webhook = new ObjectMapper().readTree(body);
    String eventType = webhook.get("eventType").asText();
    String webhookId = webhook.get("webhookId").asText();
    System.out.printf("Received %s (%s)%n", eventType, webhookId);
 
    return ResponseEntity.ok().build();
  }
 
  public static void main(String[] args) {
    SpringApplication.run(WebhookApplication.class, "--server.port=3000");
  }
}

using System.Security.Cryptography;
using System.Text;
using System.Text.Json;
 
var secret = Encoding.UTF8.GetBytes(
    Environment.GetEnvironmentVariable("PARADYM_WEBHOOK_SECRET")!);
 
var app = WebApplication.Create(args);
 
app.MapPost("/webhook", async (HttpRequest request) =>
{
    // The signature covers the exact bytes that were sent, so use the raw body.
    using var stream = new MemoryStream();
    await request.Body.CopyToAsync(stream);
    var body = stream.ToArray();
    var header = request.Headers["X-Paradym-HMAC-SHA-256"].ToString();
    var signature = Encoding.UTF8.GetBytes(header);
    var hash = HMACSHA256.HashData(secret, body);
    var digest = Convert.ToHexString(hash).ToLowerInvariant();
    var expected = Encoding.UTF8.GetBytes(digest);
 
    // Compare in constant time, so timing does not reveal the expected signature.
    if (!CryptographicOperations.FixedTimeEquals(signature, expected))
    {
        return Results.Unauthorized();
    }
 
    var webhook = JsonDocument.Parse(body).RootElement;
    var eventType = webhook.GetProperty("eventType");
    var webhookId = webhook.GetProperty("webhookId");
    Console.WriteLine($"Received {eventType} ({webhookId})");
 
    return Results.Ok();
});
 
app.Run("http://localhost:3000");

<?php
// Serve this file at /webhook, or run it with `php -S localhost:3000 webhook.php`.
$secret = getenv('PARADYM_WEBHOOK_SECRET');
 
// The signature covers the exact bytes that were sent, so use the raw body.
$body = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_PARADYM_HMAC_SHA_256'] ?? '';
$expected = hash_hmac('sha256', $body, $secret);
 
// Compare in constant time, so timing does not reveal the expected signature.
if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    exit;
}
 
$webhook = json_decode($body, true);
error_log("Received {$webhook['eventType']} ({$webhook['webhookId']})");
 
http_response_code(200);

From now on, all events you selected are sent to the URL of the webhook subscription. You can create multiple webhook subscriptions, and each one receives every event it subscribes to.

Retrieving webhook subscriptions

You can list all webhook subscriptions of a wallet with GET /v1/wallets/{walletId}/webhooks, or fetch a single one by its ID with GET /v1/wallets/{walletId}/webhooks/{webhookSubscriptionId}. In the dashboard, Copy ID in the menu of a webhook subscription copies its ID. Retrieving an unknown webhook subscription returns 404. The signature secret is only returned when the webhook subscription is created, so it is never included in these responses.

Updating a webhook subscription

You can change a webhook subscription’s name and eventTypes without recreating it, either from the dashboard (open its Edit action under Settings → Webhooks) or using the update webhook API. Two endpoints are available:

• PATCH applies a partial update: send only the fields you want to change and provide at least one of name or eventTypes.
• PUT replaces the webhook subscription: both name and eventTypes are required and fully replace the current values.

When eventTypes is provided it fully replaces the existing set.

The url of a webhook subscription is immutable and cannot be changed. To point events at a different URL, create a new webhook subscription and delete the old one. The signature secret is never changed by an update.

Timeouts and retries

A webhook is delivered when your server responds with a 2xx status code within 5 seconds. Any other response, a timeout, a connection error or a redirect counts as a failed attempt, and the webhook is retried. Respond as soon as you have safely stored the event, and do any slow processing afterwards.

A failed webhook is retried 10 times. Each retry waits after the previous failed attempt, starting at 1 minute and growing to 24 hours:

When the last retry fails, about 3 days after the first attempt, the webhook is marked as failed. Retries are sent by a job that runs every minute, so each one can go out up to a minute later than its wait.

Every attempt sends exactly the same request body, with the same webhookId and signature. The X-Paradym-Webhook-Delivery-Id header identifies the webhook sent to your endpoint: it is the same on every attempt and matches the delivery id in the API. The X-Paradym-Webhook-Attempt-Id header is different on every attempt and matches the attempt id in the API. A webhook can therefore reach you more than once, for example when your server processed it but responded too late, so use webhookId to skip webhooks you have already processed. Retried webhooks can also arrive out of order. When the order matters, use webhookPublishedAt or retrieve the latest state through the API.

The openid4vc.verification.data and didcomm.verification.data events contain credential data, so Paradym keeps them for 15 minutes only. They get the retries that fit in that time, the first four, sent about 1, 3, 6 and 10 minutes after the first attempt, and can be redelivered until then. After 15 minutes the webhook is removed and a delivery that hasn’t succeeded is marked as failed. The delivery history still shows the result of every attempt. If you can’t rely on your endpoint being reachable, see Verification data access for retrieving the data through the API instead.

How webhooks are recorded

• A webhook subscription is a URL you registered to receive webhooks, identified by webhookSubscriptionId in the API (/webhooks/{webhookSubscriptionId}).
• A webhook is one event sent to you, identified by the webhookId in its body. Use it to skip webhooks you already processed.
• A delivery is one webhook sent to one webhook subscription. It has the status (pending, delivered or failed), the retry schedule and an id, sent in the X-Paradym-Webhook-Delivery-Id header.
• An attempt is one HTTP request of a delivery, with its status code or error code and an id, sent in the X-Paradym-Webhook-Attempt-Id header.

For example, a webhook sent to two webhook subscriptions has two deliveries with the same webhookId. If one of them fails once and then succeeds, that delivery has two attempts.

Delivery history and redelivery

Paradym keeps a record of every webhook and the result of each attempt for 30 days. The webhook itself is removed from a delivery once it is delivered, so it is only available until then. Webhooks with verification data are removed after 15 minutes at the latest. Use the API to see the deliveries, the result of every attempt and the exact webhook, and to redeliver webhooks:

• List the deliveries  of every webhook subscription, optionally filtered by webhookSubscriptionId, status or date. Each delivery has the webhookSubscriptionId it was sent to, so filtering on status=failed shows which webhook subscriptions have failing deliveries.
• Get a summary of the deliveries : how many are pending, delivered and failed. It takes the same webhookSubscriptionId and createdAt filters as the list, so you can count the deliveries of one webhook subscription or of a shorter period, for example the last hour. Without a createdAt filter it covers the last 30 days.
• Retrieve a delivery  to see the status code or error and the duration of every attempt and, while it is still stored, the exact webhook. The duration (durationMs) is the time from sending the request until your server’s response headers were received, or until the attempt failed or timed out.
• Redeliver a pending or failed delivery  right away and get the delivery with the result of every attempt.
• Redeliver all pending and failed deliveries , of every webhook subscription or of one, for example once your server is back after an outage, without waiting for the next retry.

A redelivered webhook keeps its webhookId. A redelivery is a single extra attempt that leaves the retry schedule alone: if it fails, a failed webhook stays failed, and a retrying webhook keeps its next retry where it was. A delivery can be redelivered at most 10 times. A delivered webhook can’t be redelivered, and neither can a webhook with verification data after 15 minutes.

Redelivering a single delivery sends it right away and returns the result, unless its first attempt hasn’t been sent yet or an attempt for it is in progress. Redelivering all pending and failed deliveries sends them in the background instead, a limited number per endpoint per minute, so a large backlog does not flood your server. Deliveries that can’t be redelivered are skipped, and scheduledCount in the response tells you how many will be sent.

Each attempt shows what triggered it: initial for the first attempt, scheduled for an automatic retry and manual for a redelivery, of that delivery or of all pending and failed deliveries. A failed attempt has an error with a message and one of these code values:

Webhook Events

Every delivered event contains a walletId field identifying the wallet the event belongs to. A deprecated projectId field with the same value is also included (projects are now called wallets). We recommend to only use the walletId.

The events emitted by Paradym are divided into categories:

• OpenID4VC
• DIDComm
• Certificates
• Trusted Entities

OpenID4VC

The following OpenID4VC webhook events are currently emitted:

• openid4vc.issuance.offered
• openid4vc.issuance.offerRetrieved
• openid4vc.issuance.partiallyIssued
• openid4vc.issuance.completed
• openid4vc.issuance.failed
• openid4vc.issuance.expired
• openid4vc.verification.requested
• openid4vc.verification.requestRetrieved
• openid4vc.verification.pendingRedirect
• openid4vc.verification.verified
• openid4vc.verification.data
• openid4vc.verification.failed
• openid4vc.verification.expired

Failure events (such as openid4vc.issuance.failed and openid4vc.verification.failed) include an error object in their payload with a numeric code. See Error Codes for the meaning of each code.

All openid4vc.issuance events contain an openId4VcIssuanceId in the payload that can be used to retrieve an OpenID4VC issuance session  using the API. Similarly, All openid4vc.verification events contain an openId4VcVerificationId in the payload that can be used to retrieve an OpenID4VC verification session  using the API.

openid4vc.issuance.offered

Event dispatched when an OpenID4VC issuance offer is created.

Example:

{
  "webhookId": "<webhook-id>",
  "webhookPublishedAt": "<time-of-publication>",
  "walletId": "<wallet-id>",
  "projectId": "<project-id>",
  "eventType": "openid4vc.issuance.offered",
  "payload": {
    "openId4VcIssuanceId": "<openid4vc-issuance-id>"
  }
}

openid4vc.issuance.offerRetrieved

Event dispatched when an OpenID4VC issuance offer is retrieved by the wallet. Dispatched once per session. Opening the invitation page or generating a QR code does not count as a retrieval.

Example:

{
  "webhookId": "<webhook-id>",
  "webhookPublishedAt": "<time-of-publication>",
  "walletId": "<wallet-id>",
  "projectId": "<project-id>",
  "eventType": "openid4vc.issuance.offerRetrieved",
  "payload": {
    "openId4VcIssuanceId": "<openid4vc-issuance-id>"
  }
}

openid4vc.issuance.deferred

Event dispatched when a credential within an OpenID4VC issuance offer is deferred.

Example:

{
  "webhookId": "<webhook-id>",
  "webhookPublishedAt": "<time-of-publication>",
  "walletId": "<wallet-id>",
  "projectId": "<project-id>",
  "eventType": "openid4vc.issuance.deferred",
  "payload": {
    "openId4VcIssuanceId": "<openid4vc-issuance-id>"
  }
}

openid4vc.issuance.partiallyIssued

Event dispatched when a credential has been issued in the OpenID4VC issuance session.

Example:

{
  "webhookId": "<webhook-id>",
  "webhookPublishedAt": "<time-of-publication>",
  "walletId": "<wallet-id>",
  "projectId": "<project-id>",
  "eventType": "openid4vc.issuance.partiallyIssued",
  "payload": {
    "openId4VcIssuanceId": "<openid4vc-issuance-id>"
  }
}

openid4vc.issuance.completed

Event dispatched when all credentials have been issued in the OpenID4VC issuance session.

Example:

{
  "webhookId": "<webhook-id>",
  "webhookPublishedAt": "<time-of-publication>",
  "walletId": "<wallet-id>",
  "projectId": "<project-id>",
  "eventType": "openid4vc.issuance.completed",
  "payload": {
    "openId4VcIssuanceId": "<openid4vc-issuance-id>"
  }
}

openid4vc.issuance.failed

Event dispatched when an OpenID4VC issuance failed.

Example:

{
  "webhookId": "<webhook-id>",
  "webhookPublishedAt": "<time-of-publication>",
  "walletId": "<wallet-id>",
  "projectId": "<project-id>",
  "eventType": "openid4vc.issuance.failed",
  "payload": {
    "openId4VcIssuanceId": "<openid4vc-issuance-id>",
    "error": {
      "message": "error-message",
      "code": "error-code",
      "details": "error-details"
    }
  }
}

openid4vc.issuance.expired

Event dispatched when an OpenID4VC issuance session has expired.

Example:

{
  "webhookId": "<webhook-id>",
  "webhookPublishedAt": "<time-of-publication>",
  "walletId": "<wallet-id>",
  "projectId": "<project-id>",
  "eventType": "openid4vc.issuance.expired",
  "payload": {
    "openId4VcIssuanceId": "<openid4vc-issuance-id>"
  }
}

openid4vc.verification.requested

Event dispatched when an OpenID4VC verification request is created.

Example:

{
  "webhookId": "<webhook-id>",
  "webhookPublishedAt": "<time-of-publication>",
  "walletId": "<wallet-id>",
  "projectId": "<project-id>",
  "eventType": "openid4vc.verification.requested",
  "payload": {
    "openId4VcVerificationId": "<openid4vc-verification-id>"
  }
}

openid4vc.verification.requestRetrieved

Event dispatched when an OpenID4VC verification request is retrieved by the wallet. Dispatched once per session. Opening the invitation page or generating a QR code does not count as a retrieval.

Example:

{
  "webhookId": "<webhook-id>",
  "webhookPublishedAt": "<time-of-publication>",
  "walletId": "<wallet-id>",
  "projectId": "<project-id>",
  "eventType": "openid4vc.verification.requestRetrieved",
  "payload": {
    "openId4VcVerificationId": "<openid4vc-verification-id>"
  }
}

openid4vc.verification.pendingRedirect

Event dispatched when the wallet has responded in an OpenID4VC verification session that uses the redirect flow. The outcome, verified or failed, is withheld until the session is completed with the challenge and response_code. Only dispatched for sessions created with both a challenge and a redirectUri. The openid4vc.verification.verified or openid4vc.verification.failed event follows once the session is completed. Like the redirect flow itself, this event is experimental and subject to change.

Example:

{
  "webhookId": "<webhook-id>",
  "webhookPublishedAt": "<time-of-publication>",
  "walletId": "<wallet-id>",
  "projectId": "<project-id>",
  "eventType": "openid4vc.verification.pendingRedirect",
  "payload": {
    "openId4VcVerificationId": "<openid4vc-verification-id>"
  }
}

openid4vc.verification.verified

Event dispatched when the presentation in an OpenID4VC verification session has been verified.

Example:

{
  "webhookId": "<webhook-id>",
  "webhookPublishedAt": "<time-of-publication>",
  "walletId": "<wallet-id>",
  "projectId": "<project-id>",
  "eventType": "openid4vc.verification.verified",
  "payload": {
    "openId4VcVerificationId": "<openid4vc-verification-id>"
  }
}

openid4vc.verification.data

Event dispatched when the presentation in an OpenID4VC verification session has been verified. However, in addition to the openid4vc.verification.verified event, this event also contains the data from the credentials received in a verification. When the presentation template declares transactions, it also contains the transactionData the holder signed, with the credential that signed each entry. See authorizing a transaction.

This event is only emitted if you have set the verificationDataAccess to webhook in your wallet settings, in which case the data cannot be retrieved through the API. Paradym keeps this webhook for at most 15 minutes to retry it when your endpoint does not respond. See Verification data access for the other options. It is not emitted for flows that release the data themselves: the redirect flow returns it when completing the session, and verification with OpenID Connect in the ID token. Paradym holds it until that release or until the session expires.

Example:

{
  "webhookId": "<webhook-id>",
  "webhookPublishedAt": "<time-of-publication>",
  "walletId": "<wallet-id>",
  "projectId": "<project-id>",
  "eventType": "openid4vc.verification.data",
  "payload": {
    "openId4VcVerificationId": "<openid4vc-verification-id>",
    "openId4VcVerification": {
      // OpenId4VcVerification session as returned by the API, including the
      // presented credentials and, when declared, the signed transactionData
    }
  }
}

openid4vc.verification.failed

Event dispatched when an OpenID4VC verification failed.

Example:

{
  "webhookId": "<webhook-id>",
  "webhookPublishedAt": "<time-of-publication>",
  "walletId": "<wallet-id>",
  "projectId": "<project-id>",
  "eventType": "openid4vc.verification.failed",
  "payload": {
    "openId4VcVerificationId": "<openid4vc-verification-id>",
    "error": {
      "message": "error-message",
      "code": "error-code",
      "details": "error-details"
    }
  }
}

openid4vc.verification.expired

Event dispatched when an OpenID4VC verification session has expired.

Example:

{
  "webhookId": "<webhook-id>",
  "webhookPublishedAt": "<time-of-publication>",
  "walletId": "<wallet-id>",
  "projectId": "<project-id>",
  "eventType": "openid4vc.verification.expired",
  "payload": {
    "openId4VcVerificationId": "<openid4vc-verification-id>"
  }
}

DIDComm

The following DIDComm webhook events are currently emitted:

• didcomm.connection.created
• didcomm.connection.reused
• didcomm.messaging.basic.received
• didcomm.messaging.custom.received
• didcomm.invitation.expired
• didcomm.issuance.offered
• didcomm.issuance.completed
• didcomm.issuance.failed
• didcomm.issuance.expired
• didcomm.verification.requested
• didcomm.verification.verified
• didcomm.verification.data
• didcomm.verification.failed
• didcomm.verification.expired

All didcomm.issuance events contain an didcommIssuanceId in the payload that can be used to retrieve a DIDComm issuance session  using the API. Similarly, All didcomm.verification events contain an didcommVerificationId in the payload that can be used to retrieve a DIDComm verification session  using the API.

didcomm.connection.created

Event dispatched when a DIDComm connection is created based on a created invitation. This event is not emitted for connections created based on received invitations (for this you get back the connection directly when receiving the invitation).

Example:

{
  "webhookId": "<webhook-id>",
  "webhookPublishedAt": "<time-of-publication>",
  "walletId": "<wallet-id>",
  "projectId": "<project-id>",
  "eventType": "didcomm.connection.created",
  "payload": {
    "didcommInvitationId": "<didcomm-invitation-id>",
    "didcommConnectionId": "<didcomm-connection-id>"
  }
}

didcomm.connection.reused

Event dispatched when a DIDComm connection is reused based on a created invitation. This event is not emitted for connections reused based on received invitations (for this you get back the connection directly when receiving the invitation).

Example:

{
  "webhookId": "<webhook-id>",
  "webhookPublishedAt": "<time-of-publication>",
  "walletId": "<wallet-id>",
  "projectId": "<project-id>",
  "eventType": "didcomm.connection.reused",
  "payload": {
    "didcommInvitationId": "<didcomm-invitation-id>",
    "didcommConnectionId": "<didcomm-connection-id>"
  }
}

didcomm.messaging.basic.received

Event dispatched when a basic message is received.

Example:

{
    "webhookId": "<webhook-id>",
    "webhookPublishedAt": "<time-of-publication>",
    "walletId": "<wallet-id>",
    "projectId": "<project-id>",
    "eventType": "didcomm.messaging.basic.received",
    "payload": {
        "didcommConnectionId": "<existing-connection-id>",
        "message": "<message-content>",
        "messageId": "<received-message-id>",
        "sentTime": "<sent-time>"
    }
}

didcomm.messaging.custom.received

Event dispatched when a custom message is received.

Example:

{
    "webhookId": "<webhook-id>",
    "webhookPublishedAt": "<time-of-publication>",
    "walletId": "<wallet-id>",
    "projectId": "<project-id>",
    "eventType": "didcomm.messaging.custom.received",
    "payload": {
        "didcommConnectionId": "<existing-connection-id>",
        "message": {
          "@id": "<message-id>",
          "@type": "<message-type>",
          "<custom-message-field>": "<custom-message-value>"
        }
    }
}

didcomm.invitation.expired

Event dispatched when a DIDComm invitation has expired.

Example:

{
  "webhookId": "<webhook-id>",
  "webhookPublishedAt": "<time-of-publication>",
  "walletId": "<wallet-id>",
  "projectId": "<project-id>",
  "eventType": "didcomm.invitation.expired",
  "payload": {
    "didcommInvitationId": "<didcomm-invitation-id>"
  }
}

didcomm.issuance.offered

Event dispatched when a DIDComm issuance offer is created.

Example:

{
  "webhookId": "<webhook-id>",
  "webhookPublishedAt": "<time-of-publication>",
  "walletId": "<wallet-id>",
  "projectId": "<project-id>",
  "eventType": "didcomm.issuance.offered",
  "payload": {
    "openId4VcIssuanceId": "<didcomm-issuance-id>"
  }
}

didcomm.issuance.completed

Event dispatched when the credential has been issued in the DIDComm issuance session.

Example:

{
  "webhookId": "<webhook-id>",
  "webhookPublishedAt": "<time-of-publication>",
  "walletId": "<wallet-id>",
  "projectId": "<project-id>",
  "eventType": "didcomm.issuance.completed",
  "payload": {
    "openId4VcIssuanceId": "<didcomm-issuance-id>"
  }
}

didcomm.issuance.failed

Event dispatched when a DIDComm issuance failed.

Example:

{
  "webhookId": "<webhook-id>",
  "webhookPublishedAt": "<time-of-publication>",
  "walletId": "<wallet-id>",
  "projectId": "<project-id>",
  "eventType": "didcomm.issuance.failed",
  "payload": {
    "openId4VcIssuanceId": "<didcomm-issuance-id>",
    "error": {
      "message": "error-message",
      "code": "error-code",
      "details": "error-details"
    }
  }
}

didcomm.issuance.expired

Event dispatched when a DIDComm issuance session has expired.

Example:

{
  "webhookId": "<webhook-id>",
  "webhookPublishedAt": "<time-of-publication>",
  "walletId": "<wallet-id>",
  "projectId": "<project-id>",
  "eventType": "didcomm.issuance.expired",
  "payload": {
    "didcommIssuanceId": "<didcomm-issuance-id>"
  }
}

didcomm.verification.requested

Event dispatched when a DIDComm verification request is created.

Example:

{
  "webhookId": "<webhook-id>",
  "webhookPublishedAt": "<time-of-publication>",
  "walletId": "<wallet-id>",
  "projectId": "<project-id>",
  "eventType": "didcomm.verification.requested",
  "payload": {
    "didcommVerificationId": "<didcomm-verification-id>"
  }
}

didcomm.verification.verified

Event dispatched when the presentation in a DIDComm verification session has been verified.

Example:

{
  "webhookId": "<webhook-id>",
  "webhookPublishedAt": "<time-of-publication>",
  "walletId": "<wallet-id>",
  "projectId": "<project-id>",
  "eventType": "didcomm.verification.verified",
  "payload": {
    "didcommVerificationId": "<didcomm-verification-id>"
  }
}

didcomm.verification.data

Event dispatched when the presentation in a DIDComm verification session has been verified. However in addition to the didcomm.verification.verified event, this event also contains the data from the credentials received in a verification.

This event is only emitted if you have set the verificationDataAccess to webhook in your wallet settings, in which case the data cannot be retrieved through the API. Paradym keeps this webhook for at most 15 minutes to retry it when your endpoint does not respond. See Verification data access for the other options.

Example:

{
  "webhookId": "<webhook-id>",
  "webhookPublishedAt": "<time-of-publication>",
  "walletId": "<wallet-id>",
  "projectId": "<project-id>",
  "eventType": "didcomm.verification.data",
  "payload": {
    "didcommVerificationId": "<didcomm-verification-id>",
    "didcommVerification": {
      // DidcommVerification session with data as returned by the API
    }
  }
}

Event dispatched when the presentation in a DIDComm verification session has been verified.

Example:

{
  "webhookId": "<webhook-id>",
  "webhookPublishedAt": "<time-of-publication>",
  "walletId": "<wallet-id>",
  "projectId": "<project-id>",
  "eventType": "didcomm.verification.verified",
  "payload": {
    "didcommVerificationId": "<didcomm-verification-id>"
  }
}

didcomm.verification.failed

Event dispatched when a DIDcomm verification failed.

Example:

{
  "webhookId": "<webhook-id>",
  "webhookPublishedAt": "<time-of-publication>",
  "walletId": "<wallet-id>",
  "projectId": "<project-id>",
  "eventType": "didcomm.verification.failed",
  "payload": {
    "didcommVerificationId": "<didcomm-verification-id>",
    "error": {
      "message": "error-message",
      "code": "error-code",
      "details": "error-details"
    }
  }
}

didcomm.verification.expired

Event dispatched when a DIDComm verification session has expired.

Example:

{
  "webhookId": "<webhook-id>",
  "webhookPublishedAt": "<time-of-publication>",
  "walletId": "<wallet-id>",
  "projectId": "<project-id>",
  "eventType": "didcomm.verification.expired",
  "payload": {
    "didcommVerificationId": "<didcomm-verification-id>"
  }
}

Certificates

The following certificate webhook events are currently emitted:

• certificate.renewal.required

certificate.renewal.required

Event dispatched when a root certificate is nearing its expiration date, serving as a reminder for necessary renewal actions.

Example:

{
  "webhookId": "<webhook-id>",
  "webhookPublishedAt": "<time-of-publication>",
  "walletId": "<wallet-id>",
  "projectId": "<project-id>",
  "eventType": "certificate.renewal.required",
  "payload": {
    "certificateId": "<certificate-id>",
    "certificateType": "<certificate-type>",
    "expirationDate": "<certificate-expiration-date>"
  }
}

Trusted Entities

The following trusted entities webhook events are currently emitted:

• trustedEntity.etsiLote.update.failed

trustedEntity.etsiLote.update.failed

Event dispatched when an attempt to update the ETSI LoTE information for a trusted entity has failed.

Example:

{
  "webhookId": "<webhook-id>",
  "webhookPublishedAt": "<time-of-publication>",
  "walletId": "<wallet-id>",
  "projectId": "<project-id>",
  "eventType": "trustedEntity.etsiLote.update.failed",
  "payload": {
    "trustedEntityId": "<trusted-entity-id>",
    "etsiLoteUrl": "<etsi-lote-url>",
    "error": "<error>",
    "disabled": "<whether-etsi-lote-is-disabled>"
  }
}