Webhooks

The K42 platform communicates events back to you and your Publisher instance via webhooks. When actions occur on the platform - such as a cashback being triggered or a loyalty program qualifying purchase being recorded - an event is dispatched to your registered webhook endpoints.

Overview

The webhook system delivers structured event payloads to an HTTPS endpoint you control. Key characteristics:

• At-least-once delivery - every event is guaranteed to reach your endpoint, but may arrive more than once
• Ordered and batched - events are delivered in order, and sometimes grouped into batches per webhook
• Signed - every delivery includes an HMAC-SHA256 signature to verify that it was us who sent the payload
• Automatic retries - failed deliveries are retried indefinitely with exponential backoff

Getting Started

1. Register a webhook with your callback URL and subscribed event types
2. Implement signature verification in your handler
3. Process events and deduplicate by event_id (Cashback, Loyalty)

Payload Structure

Each webhook delivery is a JSON object with a single events array:

{
  "events": [
    {
      "event_id": "evt_abc123",
      "timestamp": "2024-01-15T10:30:00Z",
      "type": "cashback.created",
      ...
    }
  ]
}

Every event includes these base fields:

Field	Type	Description
event_id	string	Unique identifier for this event (use for deduplication)
timestamp	string	ISO 8601 timestamp of when the event occurred
type	string	The event type

Available Event Types

Event Type	Description
cashback.created	A cashback reward was triggered for a transaction
cashback.cleared	A pending cashback has settled
cashback.reverted	A cashback was reversed
qualifying_purchase.created	A transaction counted as a stamp toward a loyalty program
qualifying_purchase.voided	A qualifying purchase was voided
qualifying_purchase.unredeemed	A qualifying purchase was marked unredeemed