POS Webhook Reference

Webhooks allow your external systems to receive real-time notifications when events occur in Cockato. Instead of polling the API for changes, webhooks push data to your system instantly.

---

Overview

When certain events happen — like a customer earning points or completing a punch card — Cockato sends an HTTP POST request to your configured webhook URL with details about the event.

💡 Tip: Webhooks are ideal for keeping your POS, CRM, or analytics systems in sync with Cockato in real time.

---

Webhook Endpoint

Configure your webhook to receive events at:

• Endpoint: https://your-project.supabase.co/functions/v1/pos-webhook
• Method: POST
• Content-Type: application/json

---

Authentication

Webhook requests are authenticated via:

• API Key: Validated through the x-api-key header
• The key must match an active API key in your organization

⚠️ Important: Always validate the x-api-key header on incoming webhook requests to ensure they're genuinely from Cockato.

---

Event Types

📝 Note: New event types may be added over time. Your webhook handler should gracefully ignore unrecognized event types.

---

Payload Format

Webhook payloads are JSON objects with a consistent structure:

{
  "event": "transaction.completed",
  "timestamp": "2025-01-15T10:30:00Z",
  "data": {
    "customer_id": "uuid",
    "customer_name": "Jane Smith",
    "barcode_id": "CKT12345678",
    "points_awarded": 50,
    "new_balance": 350,
    "transaction_amount": 50.00,
    "outlet_id": "uuid"
  }
}

The data object varies by event type but always includes the relevant customer and transaction details.

---

Error Handling

• Cockato expects a 2xx response from your webhook endpoint
• Failed deliveries may be retried automatically
• If your endpoint consistently fails, the webhook may be temporarily paused

💡 Tip: Return a 200 OK response as quickly as possible, then process the webhook data asynchronously. This prevents timeouts.

---

Security Best Practices

1. Validate the API key on every incoming request
2. Use HTTPS for your webhook endpoint — never accept webhooks over plain HTTP
3. Validate payload structure before processing to prevent injection attacks
4. Implement idempotency — handle potential duplicate deliveries by checking if you've already processed an event
5. Log all payloads during development to understand the data structure

⚠️ Warning: Never trust webhook data blindly. Always validate the API key and verify the payload structure matches what you expect.

---

Testing Webhooks

During development:

1. Use a tool like RequestBin or ngrok to create a temporary webhook endpoint
2. Trigger events in Cockato (e.g., award points to a test customer)
3. Inspect the incoming webhook payloads
4. Build your handler based on the observed data structure

---

Frequently Asked Questions

How quickly are webhooks delivered? Webhooks are sent within seconds of the triggering event. Exact timing depends on network conditions.

What if my endpoint is down? Failed webhook deliveries may be retried. However, you should not rely on webhooks as the sole source of truth — use the API to reconcile data periodically.

Can I receive webhooks for specific event types only? Currently, all event types are sent to the same endpoint. Filter events in your handler by checking the event field.

Are webhook payloads signed? Webhooks are authenticated via the API key in the x-api-key header. Validate this header on every request.