Webhooks

Webhooks are used to notify external systems of platform events in real-time. Each event is delivered via HTTP POST to the registered endpoint.

Real-Time Notifications

Webhook support is available for all important events such as credential issuance, connection establishment, and proof verification. Payload security is ensured with HMAC signature.

Webhook Architecture

Events from SSI Agent are processed and delivered to external endpoints:

Supported Events

Event	Description	Payload
connection.created	New connection	connection_id, state
connection.active	Connection active	connection_id
credential.issued	Credential issued	credential_id, schema_id
credential.received	Credential received	credential_id
credential.revoked	Credential revoked	credential_id
proof.requested	Proof requested	proof_id
proof.verified	Proof verified	proof_id, verified

Webhook Configuration

Event Payload Structure

Field	Type	Description
event_type	string	Event type
timestamp	ISO8601	Event time
payload	object	Event data
signature	string	HMAC signature

📄 Example Webhook Payload

credential.issued Event

{
  "event_type": "credential.issued",
  "timestamp": "2024-12-19T10:30:00Z",
  "payload": {
    "credential_id": "cred-abc-123",
    "connection_id": "conn-xyz-789",
    "schema_id": "diploma_schema:1.0",
    "state": "issued",
    "holder_label": "Holder Wallet"
  },
  "signature": "sha256=a1b2c3d4e5f6..."
}

Signature Verification:

webhook-verify.js

const crypto = require('crypto');
const expectedSig = 'sha256=' + crypto
  .createHmac('sha256', WEBHOOK_SECRET)
  .update(JSON.stringify(body))
  .digest('hex');
const isValid = expectedSig === request.headers['x-signature'];

Security

Feature	Description
HMAC Signature	Payload integrity verification
HTTPS	TLS encrypted transmission
Retry Logic	Failed delivery retry
IP Whitelist	Source IP filtering