External API Connector

The External API connector allows Kiwire to push user events — login, logout, registration, and voucher redemption — to external systems via HTTP webhooks or API calls. Use it to sync WiFi session data with a CRM, award loyalty points on guest login, notify a billing system when a user connects, or feed event data into an analytics platform.

'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-api/overview.png

Use Cases

• CRM sync — push guest registration data to Salesforce, HubSpot, or Zoho CRM on first login, building a WiFi-verified contact list
• Loyalty system integration — award points to a hotel loyalty or retail rewards system when a guest successfully connects
• Billing system notification — trigger invoice generation or usage recording in an external billing platform when a session starts
• Analytics pipeline — push login events to a data warehouse (BigQuery, Snowflake) or a real-time analytics stream (Segment, Mixpanel) for visitor behaviour analysis
• Access control — notify a physical access control system when a device authenticates to specific SSIDs or zones

Configuration Fields

Field	Description
name	Instance label for this API connector (e.g., Salesforce CRM, Loyalty API)
is_active	Enable or disable this connector without losing configuration. When disabled, no events are sent.
endpoint_url	The full URL of the external API or webhook endpoint that receives the event payload (e.g., https://hooks.example.com/kiwire-events). Must be HTTPS in production.
method	HTTP method for the outbound request: GET, POST, or PUT. Webhooks almost always use POST.
auth_type	Authentication scheme for the request. Options: none, bearer (Authorization: Bearer {token}), basic (HTTP Basic Auth), api_key_header (custom header name + value).
auth_value	Token, password, or API key value corresponding to the selected auth_type. Stored encrypted at rest. For Basic Auth, encode as username:password.
headers	Additional HTTP headers to include in every request, as a JSON object (e.g., {"Content-Type": "application/json", "X-Source": "kiwire"}). Merged with any auth headers.
body_template	The request body template (JSON or form-encoded). Supports placeholder variables — see Payload Variables below.

Event Triggers

Configure which Kiwire events cause an API call to be sent. Each trigger is independently enabled or disabled:

Event	When it fires
login	A user successfully authenticates through the captive portal or enterprise portal and is granted network access
logout	A user's session ends — either through RADIUS accounting session-stop, manual logout, or session timeout
registration	A new Kiwire user account is created — either self-registered on the portal, auto-provisioned from AD/LDAP/SSO, or created by an admin
voucher_redeem	A guest redeems a voucher code on the captive portal

Payload Variables

The following variables are available in the body_template and endpoint_url. They are substituted with real values at the time the event fires:

Variable	Replaced with
{{event}}	The event type: login, logout, registration, or voucher_redeem
{{username}}	The user's Kiwire username
{{email}}	The user's email address
{{fullname}}	The user's full name
{{phone}}	The user's phone number
{{ip}}	The user's IP address at the time of the event
{{mac}}	The user's device MAC address
{{zone}}	The zone name the user connected through
{{ssid}}	The SSID name the user connected to
{{timestamp}}	ISO 8601 UTC timestamp of the event (e.g., 2026-06-18T09:30:00Z)
{{tenant_id}}	The tenant's unique identifier
{{session_id}}	The RADIUS accounting session ID (available for login and logout events)

Example Body Template

{
    "event": "{{event}}",
    "user": {
        "username": "{{username}}",
        "email": "{{email}}",
        "name": "{{fullname}}",
        "phone": "{{phone}}"
    },
    "session": {
        "ip": "{{ip}}",
        "mac": "{{mac}}",
        "zone": "{{zone}}",
        "ssid": "{{ssid}}",
        "session_id": "{{session_id}}"
    },
    "occurred_at": "{{timestamp}}"
}

Retry Behaviour

If the external API call fails (non-2xx response or connection timeout), Kiwire automatically retries the delivery:

Attempt	Delay before retry
1st retry	30 seconds
2nd retry	5 minutes (exponential backoff)
3rd retry	30 minutes
Final failure	Event is moved to the failed jobs queue. Inspect with php artisan queue:failed.

Retries are handled by Kiwire's background queue workers. Ensure the queue worker is running to guarantee delivery. Failed jobs can be retried from the server using the queue management Artisan command.

Testing the Configuration

Click Send Test Request after saving to verify the endpoint is reachable and the template is valid. Kiwire sends a POST request with the body template populated with placeholder values (sample data, not real user data). Check your endpoint's logs or request inspector to confirm the payload format is correct.

Multiple Instances

You can configure multiple External API connector instances, each pointing to a different system. For example, configure one instance for a CRM (fires on registration) and another for a loyalty system (fires on login). Each instance has its own endpoint, auth settings, event triggers, and body template.

Required Permissions

view-connector-api · edit-connector-api