Webhooks

A Webhook connector sends an HTTPS POST request to a URL you control every time a subscribed platform event occurs — in real time, without polling.

Webhooks are designed for service-to-service communication in a PUSH model. When a subscribed event fires, Loyal Guru sends an HTTPS POST with a JSON body to the specified URL.

warning

Your webhook endpoint must accept both POST and GET requests from Loyal Guru. Ensure your infrastructure is ready before activating in production.

Create Connector

Go to Customers → Webhooks & Connectors → New Connector → Webhook.

Field	Description
Name	Internal label for the webhook
Status	Activated or deactivated
URL	The external HTTPS endpoint that receives the POST request
Authentication	No Auth or JWT
Secret	Auto-generated by LG when JWT is selected (visible in the connector's Show view)
Headers	Optional custom HTTP headers to include in each request

JWT Authentication

When JWT authentication is selected, Loyal Guru generates a secret key after the connector is saved. To view the secret, open the connector's Show view and click the eye icon.

On each webhook delivery, Loyal Guru includes a JWT token in the request header, generated with the HS256 algorithm using the secret key.

Token header:

{
  "alg": "HS256",
  "typ": "JWT"
}

Token payload:

{
  "connector_id": 123,
  "connector_action_id": 456,
  "expires_at": 1743494030
}

expires_at is a Unix timestamp. Tokens expire 5 minutes after generation. Your endpoint should decrypt the token with the Loyal Guru-provided secret key and validate that expires_at has not passed.

The full token is generated as:

HMACSHA256(base64UrlEncode(header) + "." + base64UrlEncode(payload), SECRET_KEY)

Edit and Delete Connector

To edit an existing connector, click the Edit button from the connectors list.

note

To delete a connector, you must first delete all Actions within it individually. Only once all actions are removed can the connector itself be deleted.

Create Actions

After saving the connector, create one or more Actions to define which events trigger the webhook. Go to the connector's detail view and click New Action.

Each action subscribes the connector to a specific platform event. See Webhook Events for the full list of available events and their payload details.

How It Works

1. You register a webhook endpoint in the Owner App with a URL, authentication method, and subscribed events.
2. Whenever a subscribed event fires, Loyal Guru sends a POST request to the endpoint with the event payload.
3. Your system processes the payload and responds with 2xx to acknowledge receipt.
4. Failed deliveries are retried with exponential backoff. Persistent failures are logged in the webhook history.

Webhook Logs

The Logs tab within the Webhooks & Connectors module shows the full history of outbound requests made by webhook connectors.

note

Logs are currently available for Webhook connectors only.

Accessing Logs

1. Go to Customers → Webhooks & Connectors from the main menu.
2. Select the Logs tab at the top of the page.

Filters

Field	Required	Description
Connectors	Yes	Filter by one or more webhook connectors
Actions	Yes	Filter by the action type (e.g., voucher redeem)
From / To	No	Date and time range. Defaults to the last 24 hours if left empty.
Status	No	Filter by delivery result: OK or ERROR

Both Connectors and Actions must have at least one value selected to run a search.

Results Table

Column	Description
ID	Unique identifier of the log entry
Creation date	Date and time in the company's configured timezone
Attempts	Number of delivery attempts for this entry
Status	OK (success) or ERROR (failure)

Click the eye icon on any row to open the full log detail: connector name, action, HTTP method, destination URL, and the complete JSON payload sent. Use the Copy JSON button to copy the payload for debugging.

Status	Meaning
OK	Delivery was successful; endpoint responded with a success status.
ERROR	Delivery failed. May be due to endpoint error, timeout, or network issue. Open the log detail to review the request and diagnose the problem.