How to create a webhook

Receive a request from DiligenceID when something happens.

Scope: webhooks.manage · Reference: Webhooks_Create

curl -sS -X POST "$MGMT/webhooks?api-version=2026-08-30" \
  -H "Authorization: ApiKey $DILIGENCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "url": "https://hooks.example.com/diligenceid",
        "events": ["credential.issued", "credential.revoked", "verification.completed"]
      }'

Store the secret now

{
  "id": "/management/webhooks/whsub_9c1e4b7a",
  "name": "whsub_9c1e4b7a",
  "type": "DiligenceID/webhooks",
  "properties": {
    "url": "https://hooks.example.com/diligenceid",
    "events": ["credential.issued", "credential.revoked", "verification.completed"],
    "status": "Active",
    "secret": "whsec_…"
  }
}

secret appears in this response and never again. Reading the subscription back returns null for it, and so does the list. If you lose it you cannot recover it — you rotate and update your receiver.

Put it in your secret store before you discard the response. You need it to verify signatures, which is the only thing that makes an incoming request trustworthy.

The URL must be reachable from the internet

https is required, and the destination must resolve to a public address. These are refused:

Refused	Why
`http://`	The payload would cross the network in the clear
`localhost`, `127.0.0.1`	Would make DiligenceID call itself
`10.x`, `172.16–31.x`, `192.168.x`	Private ranges — someone else's internal network
`169.254.169.254`	The cloud instance metadata endpoint
`file:`, `ftp:` and other schemes	Not a webhook destination

A webhook URL is a value you supply that DiligenceID then makes a request to. Without these constraints that is a server-side request forgery primitive, so they are not configurable.

The check runs again immediately before every delivery, not just at registration. A hostname that resolved to a public address today can be repointed to an internal one tomorrow.

Which events

See the event catalogue. Subscribe only to what you handle — every event you receive and discard is a request your endpoint had to accept and a delivery record that had to be written.

Your endpoint must be idempotent

You will receive the same event more than once. That is not a defect to work around; it is the delivery contract. Key on the event id, record what you have handled, and make a repeat a no-op.

Respond 2xx quickly. Do your real work afterwards, from your own queue — a slow endpoint is retried, and a retry of work already in progress is exactly the case idempotency has to cover.

Check what happened

curl -sS "$MGMT/webhook-deliveries?api-version=2026-08-30" \
  -H "Authorization: ApiKey $DILIGENCE_API_KEY"

Each record has the status, the attempt count and a short diagnostic. Not your endpoint's response body — DiligenceID does not store that.

Stop deliveries

curl -sS -X DELETE "$MGMT/webhooks/whsub_9c1e4b7a?api-version=2026-08-30" \
  -H "Authorization: ApiKey $DILIGENCE_API_KEY"

This disables the subscription and keeps its delivery history, because that history is the record of what was sent where.

Edit this page on GitHub