Webhooks

Webhooks let your backend receive asynchronous 0xkey activity events. In the current release, webhook endpoints are organization-scoped and can subscribe to activity updates.

Current scope. 0xkey currently supports the ACTIVITY_UPDATES subscription. This emits activity lifecycle events such as activity.completed and activity.failed. Balance and transaction subscriptions are not yet enabled.

Create an endpoint

You can create and manage webhook endpoints from the Dashboard under Webhooks. For API-based setup, submit a ACTIVITY_TYPE_CREATE_WEBHOOK_ENDPOINT activity:

curl --request POST \
  --url https://api.0xkey.io/public/v1/submit/create_webhook_endpoint \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Stamp: <your-api-or-webauthn-stamp>' \
  --data '{
    "type": "ACTIVITY_TYPE_CREATE_WEBHOOK_ENDPOINT",
    "timestampMs": "1781250000000",
    "organizationId": "<organization-id>",
    "parameters": {
      "url": "https://example.com/webhooks/0xkey",
      "name": "Production activity webhook",
      "subscriptions": [
        {
          "eventType": "ACTIVITY_UPDATES",
          "filtersJson": "",
          "isActive": true
        }
      ]
    }
  }'

Production webhook URLs must use https://. Local development accepts http://localhost and http://127.0.0.1.

Update or delete an endpoint

Update supports the endpoint URL, display name, and active status:

curl --request POST \
  --url https://api.0xkey.io/public/v1/submit/update_webhook_endpoint \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Stamp: <your-api-or-webauthn-stamp>' \
  --data '{
    "type": "ACTIVITY_TYPE_UPDATE_WEBHOOK_ENDPOINT",
    "timestampMs": "1781250000000",
    "organizationId": "<organization-id>",
    "parameters": {
      "endpointId": "<endpoint-id>",
      "url": "https://example.com/webhooks/0xkey",
      "name": "Production activity webhook",
      "isActive": true
    }
  }'

Updating subscriptions is not supported yet. To change subscriptions, delete and recreate the endpoint.

Delete removes the 0xkey endpoint and synchronizes the deletion to the delivery backend:

curl --request POST \
  --url https://api.0xkey.io/public/v1/submit/delete_webhook_endpoint \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Stamp: <your-api-or-webauthn-stamp>' \
  --data '{
    "type": "ACTIVITY_TYPE_DELETE_WEBHOOK_ENDPOINT",
    "timestampMs": "1781250000000",
    "organizationId": "<organization-id>",
    "parameters": {
      "endpointId": "<endpoint-id>"
    }
  }'

Delivery payload

0xkey sends a JSON POST body:

{
  "eventId": "976c99ff-2320-4f6b-9fb5-90cc706a8f49",
  "eventType": "activity.completed",
  "organizationId": "488dccf5-b0e5-46da-b830-5e86776bcf05",
  "activityId": "019eb30e-254f-7270-a177-8dca730bf487",
  "data": {
    "activityType": "ACTIVITY_TYPE_CREATE_WALLET",
    "result": {}
  },
  "timestamp": 1781250000000
}

eventId is stable across retries. Use it as your idempotency key.

Delivery headers

Every signed webhook delivery includes these X-0xkey-* headers:

X-0xkey-Organization-Id: the organization that owns the event.
X-0xkey-Event-Type: the event type, for example activity.completed.
X-0xkey-Timestamp: Unix timestamp in milliseconds for this delivery attempt.
X-0xkey-Signature-Version: signature contract version. Current value: v1.
X-0xkey-Event-Id: stable event ID, unchanged across retries.
X-0xkey-Signature-Key-Id: kid for selecting the JWKS verification key.
X-0xkey-Signature-Algorithm: current value: ed25519.
X-0xkey-Signature: lowercase hex-encoded Ed25519 signature.

Verify signatures

Fetch the public verification keys from:

curl https://api.0xkey.io/public/v1/discovery/webhooks/jwks

Match X-0xkey-Signature-Key-Id to the JWK kid. If the kid is unknown, refetch JWKS once before rejecting the delivery. The signed message is the UTF-8 prefix followed by the exact raw request body bytes:

{version}.{algorithm}.{key_id}.{timestamp_ms}.{event_id}.{raw_body}

Where:

version is the X-0xkey-Signature-Version header (currently v1).
algorithm is the X-0xkey-Signature-Algorithm header (currently ed25519).
key_id is the X-0xkey-Signature-Key-Id header.
timestamp_ms is the raw X-0xkey-Timestamp header string (Unix milliseconds).
event_id is the X-0xkey-Event-Id header.
raw_body is the exact UTF-8 request body bytes received by your server.

Example verification in TypeScript with @0xkey-io/crypto:

import { verifyWebhookFromJWKS } from "@0xkey-io/crypto";

export async function handle0xkeyWebhook(req: Request) {
  const rawBody = await req.text();

  const result = await verifyWebhookFromJWKS({
    headers: req.headers,
    body: rawBody,
    jwksUrl: "https://api.0xkey.io/public/v1/discovery/webhooks/jwks",
    maxTimestampAgeMs: 300_000,
  });

  if (!result.ok) {
    throw new Error(`webhook verification failed: ${result.reason}`);
  }

  const payload = JSON.parse(rawBody);
  return payload;
}

To verify with a pinned public key instead of JWKS:

import { verifyWebhook } from "@0xkey-io/crypto";

const result = verifyWebhook({
  headers: req.headers,
  body: rawBody,
  verificationKeys: [
    {
      keyId: process.env.ZEROXKEY_WEBHOOK_KEY_ID!,
      publicKey: process.env.ZEROXKEY_WEBHOOK_PUBLIC_KEY!, // JWKS `x` field (base64)
    },
  ],
  maxTimestampAgeMs: 300_000,
});

Parse JSON only after signature verification. Verification must use the exact raw body bytes, not a re-serialized JSON object.

Retries and idempotency

0xkey uses the delivery backend for retry and fanout. Your receiver should:

Return any 2xx status only after the event is durably accepted.
Treat duplicate eventId values as successful no-ops.
Keep processing fast; enqueue long-running work and respond quickly.
Prefer HTTPS endpoints with stable DNS and TLS certificates.

Get started

Products

Crypto ecosystems

Developers

Create an endpoint

Update or delete an endpoint

Delivery payload

Delivery headers

Verify signatures

Retries and idempotency

​Create an endpoint

​Update or delete an endpoint

​Delivery payload

​Delivery headers

​Verify signatures

​Retries and idempotency

​Related API reference

Create an endpoint

Update or delete an endpoint

Delivery payload

Delivery headers

Verify signatures

Retries and idempotency

Related API reference