Webhooks

Webhooks notify your backend when Perkamo records events and effects. Use them for fulfillment, CRM sync and operational automation that should happen outside the synchronous API request.

Configure an endpoint

Webhook endpoints must be public HTTPS URLs.

Add or update the active endpoint in Webhooks.

text

https://api.example.com/webhooks/perkamo

Perkamo delivers matching event payloads to active endpoints. The current console flow creates one active endpoint for a Space and delivers all event types to it.

Delivery payload

json

{
  "id": "evt_01J...",
  "type": "purchase.completed",
  "created_at": "2026-06-01T10:00:00.000Z",
  "data": {
    "space": {
      "slug": "commerce-live",
      "name": "Commerce Live",
      "environment": "live"
    },
    "user_id": "customer_123",
    "transaction_id": "order_1092",
    "event": "purchase.completed",
    "status": "applied",
    "occurred_at": "2026-06-01T10:00:00.000Z",
    "context": { "amount": 12900, "currency": "CZK" },
    "delta": [{ "wallet": "loyalty_points", "amount": 10 }],
    "effects": [],
    "wallet_state": { "loyalty_points": 120 }
  }
}

Headers

Perkamo sends these headers:

Header	Meaning
`user-agent`	`Perkamo-Webhook/1.0`
`x-perkamo-delivery`	Unique delivery id.
`x-perkamo-event`	Event type.
`x-perkamo-space`	Space slug.
`x-perkamo-attempt`	Attempt number.

Webhook signature headers are not part of the current v1 delivery contract. Treat x-perkamo-delivery as the idempotency key, use HTTPS endpoints only and keep the endpoint URL private until signed delivery headers are added.

Handler requirements

Return any 2xx status for success.
Respond within 5 seconds.
Store x-perkamo-delivery and make processing idempotent.
Do not assume deliveries arrive exactly once.
Alert on repeated failures before launching a campaign that depends on fulfillment.

Retries

Failed deliveries move to retrying status while attempts remain. Delivery history records status code, status text, duration and last error for console debugging.

Use the Webhooks delivery history to inspect failures and resend a delivery after your handler is fixed.

Security and keys