Skip to content
English
  • There are no suggestions because the search field is empty.

Webhook Configuration Guide

 Overview

The Webhook integration allows you to automatically send guest connection data to an external application, CRM, marketing platform, or custom endpoint whenever guests connect to your WiFi network. This enables real-time synchronization of guest information with third-party systems for automation, reporting, lead management, and custom workflows.

Common use cases include:

  • Sending guest data to a CRM
  • Creating marketing automation workflows
  • Triggering custom business processes
  • Feeding guest information into data warehouses or analytics platforms
  • Integrating with external loyalty or engagement systems

Accessing the Webhook Integration

  1. Log in to the dashboard.
  2. Navigate to Apps from the left navigation menu.
  3. Locate Webhook under the Integrations section.
  4. Click Add to create a new webhook integration.

Creating a New Webhook

After selecting Add, you will be presented with the Add Webhook configuration page.

  • Enable: Turn the integration on or off.ame:
  • Name: Enter a descriptive name for the integration.
  • Select Hotspot(s): Choose one or more hotspots that should trigger webhook events. Only guest activity occurring on the selected hotspots will be delivered to the configured endpoint.
  • Webhook URL:  Enter the HTTPS endpoint that will receive webhook events.

    Requirements:

    • Must be publicly accessible
    • Must support HTTPS
    • Must be able to receive HTTP POST requests
    • Must return a successful HTTP response to acknowledge receipt
  • New Guest Connection: Turn on to send an event when a guest connects for the first time. 

    Use this event when you want to:

    • Create a new CRM contact
    • Add a lead to a marketing platform
    • Track unique guest acquisitions
  • Return Guest Connection Turn on to send an event whenever a return guest connects again.

    Use this event when you want to:

    • Update an existing contact record
    • Measure customer return frequency
    • Trigger loyalty or re-engagement campaigns

Payload Delivery

Each event generates a signed JSON payload and sends it via an HTTP POST request.

Request Headers

Every request includes the following headers:

Content-Type: application/jsonUser-Agent: MarketingWiFi-webhooks/1.0X-MWI-Event: guest.connection.new | guest.connection.returning | pingX-MWI-Delivery: <event id>X-MWI-Signature: t=<unix timestamp>,v1=<signature>

Event Types in Headers

Event Description
guest.connection.new First-time guest connection
guest.connection.returning Returning guest connection
ping Validation/test event

Request Security

Webhook requests are cryptographically signed to verify authenticity.

The X-MWI-Signature header contains:

t=<timestamp>,v1=<signature>
Recommended validation steps:
  1. Extract the timestamp (t) and signature (v1).
  2. Recompute the signature using your configured signing secret and the raw request body.
  3. Compare your computed value with the supplied v1.
  4. Reject requests older than 5 minutes.
  5. Store event IDs to prevent duplicate processing.
This protects against:
  • Spoofed requests
  • Replay attacks
  • Duplicate event processing

Payload Structure

Webhook events are delivered in JSON format and contain the following primary sections:

Event Metadata

{ "id": "event-id", "type": "guest.connection.new", "version": 1, "created_at": "timestamp"}

Contains information about the webhook event itself.

Client Information

"client": { "id": 1234, "name": "Example Client"}

Identifies the account generating the event.

Guest Information

The guest object may include:

"guest": { "guest_id": 0, "email": "guest@example.com", "firstname": "John", "lastname": "Smith", "displayname": "John Smith", "mobilephone": "+15555555555", "birthday": "", "city": "", "state": "", "country": "US", "first_seen": "timestamp", "sms_marketing_allowed": false}

Additional profile attributes and custom fields may also be present when collected through the splash page.

Available custom fields include:

"custom1": "", "custom2": "","custom3": "", "custom4": "", "custom5": "", "custom6": "", "custom7": "","custom8": "", "custom9": "", "custom10": ""

Location Information

"location": { "hotspot_id": 0, "nas_id": "TEST"}

Provides information about where the guest connected.

Device Information

"device_mac": "00:00:00:00:00:00"

Contains the guest device MAC address when available.


Testing Your Integration

Before enabling the integration in production:

  1. Create a webhook endpoint in your application.
  2. Configure the Webhook URL.
  3. Enable the desired event types.
  4. Save the webhook.
  5. Generate a guest login event.
  6. Verify your application receives the JSON payload.
  7. Confirm signature validation is working correctly.

Troubleshooting

No Events Received

Verify:

  • The webhook is enabled.
  • The correct hotspot is selected.
  • The guest completed a successful login.
  • Your endpoint is publicly reachable.
  • HTTPS is functioning correctly.

Signature Validation Fails

Verify:

  • You are using the raw request body when generating the hash.
  • The signing secret is correct.
  • The timestamp tolerance is not overly restrictive.

Duplicate Events

Webhook deliveries may occasionally be retried.

Ensure your endpoint uses the event id or delivery identifier to detect and ignore previously processed events.


Best Practices

  • Always validate webhook signatures.
  • Support retries and idempotent processing.
  • Respond quickly with an HTTP 200 status code.
  • Process heavy operations asynchronously.
  • Log incoming webhook requests during initial deployment.
  • Monitor failed deliveries through your application's logs.

Summary

The Webhook integration provides a flexible method of delivering guest connection events to external systems in real time. By configuring a secure HTTPS endpoint and selecting the desired guest connection events, organizations can automate CRM synchronization, marketing workflows, loyalty programs, analytics pipelines, and custom business processes based on guest WiFi activity.