tokenio-webhooks

Token.io Webhooks

When to Use This Skill

• How do I receive Token.io webhooks?
• How do I verify the Token.io token-signature Ed25519 signature?
• Why is my Token.io webhook signature verification failing?
• How do I subscribe to webhooks with PUT /webhook/config?
• How do I handle PAYMENT_STATUS_CHANGED, REFUND_STATUS_CHANGED, VRP_STATUS_CHANGED, or VIRTUAL_ACCOUNT_CREDIT_RECEIVED events?
• What do the payment statuses INITIATION_PROCESSING, INITIATION_COMPLETED, and INITIATION_REJECTED mean?

How Token.io Webhooks Work (Read This First)

Token.io is an open banking / account-to-account (A2A) payments provider. Its webhooks are not HMAC and not Standard Webhooks. Every delivery is signed with an asymmetric Ed25519 signature:

• token-signature — the Ed25519 signature of the raw POST body, base64url encoded.
• token-event — the event type, e.g. PAYMENT_STATUS_CHANGED (a separate header, not a body field).

You verify with your member's Ed25519 public key from the Token Dashboard (Settings → Member Information), which is base64url-encoded (no padding). There is no shared secret — Token holds the private key, you hold the public key.

Token.io ──POST body + token-signature + token-event──▶ your endpoint
                                                          │  Ed25519.verify(publicKey, rawBody, signature)
                                                          ▼
                                          dispatch on token-event → act → return 200

Critical: the signed message is the exact raw bytes of the POST body. Capture the raw body before JSON parsing — any re-serialization (key reorder, whitespace, unicode escaping) changes the bytes and the signature will not match.

Verification (core)

Import the base64url public key as an Ed25519 JWK and verify the raw body with Node's built-in crypto — no external SDK is needed for verification. The official token-io npm package is a broad API client (used to subscribe to webhooks), not a webhook verifier, so verify manually with a crypto library.