Webhooks

DID.comms is webhook-first. There is no polling inbox — incoming sealed envelopes are pushed to your registered URL in real time.

How Webhooks Work

Call /v1/webhooks/register with your URL and the events you want to receive. You'll get a whsec_ secret for signature verification.

Receive sealed envelopes

When someone sends you a message, DID.comms pushes the envelope metadata to your URL as a POST request with a JSON body.

Verify the signature

Every webhook request includes an X-DIDComms-Signature header. Verify it using your whsec_ secret to ensure the request is authentic.

Event Types

envelope.receivedAVAILABLE

Fired when a sealed envelope is delivered to your API key. The payload includes the envelope ID, hash, sender key, encryption status, and size — but never the message content.

ROADMAP: envelope.bounced, identity.rotated, usage.threshold — planned for v1.1

Webhook Payload Schema

{
  "event": "envelope.received",
  "envelope_id": "62d0a98fc0cd688c71964f175445a92c",
  "envelope_hash": "3b220d2a58b582c1",
  "sender": "ak_b1df219019773c683a5d95089a54651e",
  "encryption": {
    "algorithm": "X25519-XSalsa20-Poly1305",
    "status": "sealed"
  },
  "metadata": {
    "payload_size_bytes": 128,
    "timestamp": "2026-06-25T19:09:07.444Z"
  }
}

eventThe event type (currently always envelope.received)

envelope_idUnique identifier for this envelope delivery

envelope_hashCryptographic hash of the sealed envelope

senderThe API key of the sender — never a raw DID

encryption.statusAlways 'sealed' — envelopes are delivered encrypted

metadata.payload_size_bytesSize of the encrypted payload in bytes

curl -X POST https://arcform-api.com/v1/webhooks/register \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-DID-API-Key: ak_YOUR_KEY" \
  -d '{
    "url": "https://yourapp.com/webhooks/didcomms",
    "events": ["envelope.received"]
  }'

Webhook Handler Example

# Webhook payloads are POST'd to your registered URL
# Verify the X-DIDComms-Signature header using your whsec_ secret
# Example payload:
# {
#   "event": "envelope.received",
#   "envelope_id": "62d0a98fc0cd...",
#   "sender": "ak_b1df21901977...",
#   "encryption": { "status": "sealed" }
# }

Integration Recipes

Production-ready patterns for Slack, Shopify, and XRPL anchoring.

View Recipes

Webhook Security

Always verify the X-DIDComms-Signature header before processing any webhook payload. Unverified requests should be rejected with a 401.

⚠Store your whsec_ secret securely — never commit it to version control

⚠Respond with 200 within 10 seconds to avoid retry escalation

⚠After 5 consecutive failures, the webhook status changes to 'failed'

⚠Failed webhooks can be re-activated from the dashboard

Managing Webhooks

List webhooks

{ action: "list" }

Delete a webhook

{ action: "delete", webhook_id: "..." }