Connectors

Webhook Connector

The Webhook connector sends real-time HTTP POST notifications to one or more external URLs whenever specific events occur in Kiwire. Use webhooks to integrate with CRMs, analytics platforms, loyalty systems, or any custom backend that needs to react to WiFi user activity as it happens.

'alt' => 'Dashboard overview', 'caption' => 'The default Kiwire dashboard layout', 'screenshot' => true, 'class' => '', ]) Drop images into: public/assets/img/docs/{page}/{filename} --}}

Image not uploaded yet public/assets/img/docs/connector-webhook/overview.png

The Webhook connector — configure endpoint URL, signing secret, and event subscriptions.

Webhooks vs External API

Kiwire offers two outbound integration mechanisms. Understanding the difference helps you choose the right one:

	Webhook Connector	External API Connector
Direction	Kiwire pushes to your system	Your system queries Kiwire
Trigger	Event-driven — fires automatically when something happens	On-demand — your system polls when it needs data
Latency	Near real-time (seconds)	Depends on your poll interval
Best for	Reacting to events — loyalty points, CRM updates, alerts	Querying user status, generating reports

Supported Events

Event	Triggered When
`user.login`	A user successfully authenticates and a session starts
`user.logout`	A user session ends (RADIUS Accounting-Stop received)
`user.created`	A new WiFi user account is created (manual, self-registration, or social login)
`user.expired`	A user account's expiry date is reached and status changes to `expired`
`voucher.redeemed`	A voucher code is successfully redeemed by a user
`topup.redeemed`	A top-up code is successfully applied to a user account

You can subscribe to as many or as few events as you need per webhook instance. Create multiple webhook instances to send different events to different destination URLs.

Configuration Fields

Field	Description
`url`	The HTTPS destination URL that Kiwire will POST event payloads to
`secret`	HMAC-SHA256 signing secret — used to generate the `X-Kiwire-Signature` header on each request
`events`	Multi-select list of events to subscribe to — only selected events will trigger this webhook
`is_active`	Enable or disable the webhook without deleting it — useful for temporarily pausing delivery

Webhook endpoints must be accessible over HTTPS. HTTP endpoints are not accepted. Ensure your server's SSL certificate is valid — Kiwire will not send to endpoints with certificate errors.

Payload Format

Every webhook POST request contains a JSON body with the following structure:

{
  "event": "user.login",
  "timestamp": "2026-06-18T08:32:10Z",
  "tenant_id": "acme-hotel",
  "data": {
    "username": "john.doe@example.com",
    "mac_address": "AA:BB:CC:DD:EE:FF",
    "zone_id": 3,
    "session_id": "SESS-9A4F2B",
    "ip_address": "10.10.1.45"
  }
}

The data object contains event-specific fields relevant to that event type. Login/logout events include session details; user.created includes account fields; voucher/topup events include the code and user details.

Signature Verification

Each webhook request includes an X-Kiwire-Signature HTTP header. The value is an HMAC-SHA256 hash of the raw request body, keyed with the secret you configured, prefixed with sha256=:

X-Kiwire-Signature: sha256=3b5d8c1a...

Your endpoint should verify this signature before processing the payload. Example in PHP:

$payload  = file_get_contents('php://input');
$expected = 'sha256=' . hash_hmac('sha256', $payload, $secret);
$received = $_SERVER['HTTP_X_KIWIRE_SIGNATURE'] ?? '';

if (!hash_equals($expected, $received)) {
    http_response_code(401);
    exit('Invalid signature');
}

Always use hash_equals() (or its equivalent) for signature comparison — do not use ===. hash_equals performs a constant-time comparison that protects against timing attacks.

Retry Policy

Kiwire considers a webhook delivery successful if your endpoint returns an HTTP 2xx status code within 30 seconds. If the delivery fails (timeout, non-2xx response, or connection error), Kiwire retries automatically:

Attempt	Delay
1st retry	30 seconds after initial failure
2nd retry	5 minutes after 1st retry
3rd retry	30 minutes after 2nd retry
Abandoned	Marked as failed; logged in Delivery Log

Failed webhook deliveries — including the request body and HTTP response — are recorded in the Delivery Log under Reporting → Delivery Log. You can manually retry individual failed deliveries from that page.

'alt' => 'Dashboard overview', 'caption' => 'The default Kiwire dashboard layout', 'screenshot' => true, 'class' => '', ]) Drop images into: public/assets/img/docs/{page}/{filename} --}}

Image not uploaded yet public/assets/img/docs/connector-webhook/delivery-log.png

The Delivery Log — view failed webhook deliveries with the full response and retry manually.

Testing a Webhook

Use the Send Test Payload button on the connector form to send a sample user.login payload to your configured URL. This lets you verify that your endpoint is reachable and that your signature verification logic is correct before enabling the webhook in production.

Required Permissions

view-connector-webhook · edit-connector-webhook