v1

latestOpenAPI 3.1.02026-08-0629140119.9 KB

Webhooks

List Webhook Public Keys

Use these keys to verify the authenticity of webhook deliveries by validating the EdDSA-Ed25519 signature.

Webhook Delivery Headers

Every webhook delivery includes these HTTP headers:

Content-Type: application/json
x-kiwify-digital-signature: Base64url-encoded signature (no padding)
x-kiwify-timestamp: Unix timestamp in milliseconds when the webhook was signed

Signature Verification Process

Extract the signature and timestamp from the webhook headers
Fetch the active public key from this endpoint (cache it for 24 hours)
Reconstruct the signed message using the PoP format:
```
{path}:POST:{body}:{timestamp}
```
Where:
- {path} is only the path portion of your registered webhook URL (e.g., /webhooks/kiwibank)
- POST is the HTTP method (always POST for webhooks)
- {body} is the raw compact JSON body (as received, without re-serialization)
- {timestamp} is the value from the x-kiwify-timestamp header
SHA-256 hash the message bytes, then verify the signature using EdDSA-Ed25519 with the public key
Validate the timestamp is within 5 minutes of current time (replay attack protection)

Response Format

Returns public keys ordered by creation date (newest first), paginated via cursor
The isActive field indicates the currently active signing key (use this one for verification)
The algorithm field confirms the signing algorithm (EdDSA-Ed25519)
Use next_cursor to fetch the next page when present

Requires ManageWebhooks permission.

get/v1/webhooks-keys

Query parameters

limitinteger nullable

Maximum number of results per page (1-100, default: 20).

cursorstring nullable

Pagination cursor in format "timestamp_micros:id".

Response

List of public keys for webhook signature verification

next_cursorstring nullable

Cursor for next page (null if no more results).

Example response

{
  "public_keys": [
    {
      "algorithm": "EdDSA-Ed25519",
      "content": "-----BEGIN PUBLIC KEY-----\nMFYwEAYHKoZIzj0CAQYFK4EEAAoDQgAEQA+bOEY57yQGYdcF0q7Ia/JPc0Hr8Il0\n/pbETwvDSM+7yCkqTPDRsdptMMaoK9UEXILOaXq9Ot5azrgQEcTetg==\n-----END PUBLIC KEY-----",
      "created_at": "2026-05-28T14:30:00Z",
      "id": 2
    }
  ]
}