Webhooks

Webhooks let Loyal Guru push event data to an external system when something important happens, such as a Customer update, voucher redemption, reward redemption, challenge enrollment, or cart creation.

Use webhooks when an external CRM, ESP, data platform, fulfillment system, or middleware needs to react to Loyal Guru events without polling the API.

How webhooks work

When a subscribed event occurs, Loyal Guru sends an HTTPS POST request with a JSON body to the configured webhook URL.

Destination requirements

Before configuring a webhook in Loyal Guru, the external system must provide an endpoint that can receive requests from Loyal Guru.

Requirement	Guidance
HTTPS endpoint	Use a stable public HTTPS URL for production.
Methods	The destination should accept POST; support GET if your setup uses connectivity checks.
JSON body	Parse JSON payloads and tolerate optional or missing fields.
Idempotency	Treat repeated deliveries of the same event as safe; retries can happen after failures.
Response	Return a success status only after the event is accepted for processing.
Logging	Log request time, event headers, payload identifier, and processing result.

Create a webhook connector

In the Owner App, go to Webhooks & Connectors and create a new connector of type Webhook.

Field	Description
Name	Connector name shown in the Owner App.
Status	Whether the connector is active. Inactive connectors do not send events.
URL	Destination URL that receives webhook requests.
Authentication	No Auth or JWT. Use JWT for production integrations.
Secret	Generated by Loyal Guru when JWT authentication is selected and the connector is saved.
Headers	Optional custom headers sent with the webhook request.

After creating the connector, create one or more actions. Each action subscribes the connector to a specific event type.

JWT authentication

When JWT authentication is enabled, Loyal Guru signs a token with HS256 and sends it in the webhook request headers.

The external system must verify the token using the secret generated in the connector configuration.

Token header:

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

Token payload:

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

expires_at is a Unix timestamp. The token expires 5 minutes after it is generated. Reject expired tokens and tokens that cannot be verified with the connector secret.

Available webhook events

The currently documented webhook events are:

Event	LG-Entity	LG-Event	Typical use
Customer create	customer	create	Sync new Customers to CRM, ESP, IAM, or data platform.
Customer update	customer	update	Keep external Customer profiles, consent, and attributes current. Also emitted when Inactivity Lifecycle sets status to inactive.
Customer delete	customer	delete	Anonymize or delete Customer data downstream. Also emitted when Inactivity Lifecycle anonymizes a dormant Customer.
Customer challenge won	customer	challenge_won	Trigger prize fulfillment, CRM journeys, or notifications.
Challenge enrolled	challenge	enrolled	Update external engagement or challenge tracking.
Score trigger	trigger	executed	React when a points trigger grants points or effects.
Redeem points	substract	executed	React when points are redeemed or subtracted.
Refer a friend score trigger	customer	refer_a_friend_executed	Trigger referral follow-up flows.
Create profile score trigger	customer	after_create_profile_executed	Trigger welcome or profile-completion flows.
Customer tier won	customer	tier_level_won	Sync tier upgrade to CRM, app, ESP, or service tools.
Customer tier lost	customer	tier_level_lost	Sync tier downgrade or expiration.
Campaign sent	campaign	delivered	React when a Targeted Delivery campaign finishes (campaign_sent).
Plan campaign sent	campaign	plan_delivered	React per campaign when an Intelligent Delivery plan finishes (plan_campaign_sent).
Plan delivered	plan	delivered	React once when an Intelligent Delivery plan is delivered (payload: plan_id).
Voucher created	voucher	created	React when a voucher is created in a unit delivery flow.
Voucher redeem	voucher	redeemed	Trigger fulfillment, reconciliation, or downstream coupon tracking.
Reward redeemed	reward	redeemed	Trigger reward fulfillment or external redemption tracking.
Cart create	activity	create	Send created cart data to external analytics or data platforms.

Payloads vary by event. The destination should use LG-Entity and LG-Event headers to route processing, then validate the JSON body for the fields required by that integration.

note

Companies that enable Inactivity Lifecycle can generate extra customer / update and customer / delete traffic on the weekly evaluation runs (and a larger first-run backlog when the policy is first turned on). Coordinate capacity with Integrations before enabling the rules in production.

note

substract is the current emitted header value documented for points redemption events. Treat it as a protocol value, even though the English word is normally spelled "subtract".

Common payload groups

Group	Examples of fields
Customer events	Customer ID/code, status, profile fields, consent fields, custom attributes, timestamps.
Challenge events	Customer ID/code, challenge ID/name, level, threshold, enrolled or won timestamps, awarded points.
Points trigger events	Trigger slug, comments, total points, scores, effects, Customer balance.
Tier events	Customer ID/code, tier ID/name, current tier, previous tier, threshold, expiration.
Voucher events	Voucher code, discount, discount type, availability window, remaining redemptions, Customer.
Reward events	Redemption ID/type, reward ID/name/type, Customer, points used, reward code, source.
Cart events	Cart ID/code, total, currency, location, Customer, lines, points, discounts, effects.

Webhook logs

Webhook Logs are available in Webhooks & Connectors > Logs. Logs currently apply to webhook connectors.

Use logs to inspect:

• Connector and action.
• Creation date in the Company's configured timezone.
• Number of delivery attempts.
• Final status: OK or ERROR.
• Method and destination URL.
• Full JSON body sent to the external endpoint.

Filters:

Filter	Notes
Connectors	Required. Select one or more webhook connectors.
Actions	Required. Select one or more actions.
From / To	Optional. If empty, the search covers the last 24 hours.
Status	Optional. Filter by OK or ERROR.

The log detail view includes a Copy JSON action to reproduce or debug a delivery manually.

Implementation checklist

• Make the receiver idempotent.
• Validate JWT when enabled.
• Reject expired JWT tokens.
• Return success only after safely accepting the event.
• Store raw event payloads for debugging and replay.
• Route events by LG-Entity and LG-Event.
• Avoid hard failures when optional fields are absent.
• Monitor ERROR logs after launch.

Troubleshooting

Symptom	What to check
No webhook is sent	Connector status, action configuration, source event availability, and whether the event actually occurred.
Webhook returns ERROR in logs	Open the log detail, inspect destination response, JSON body, URL, timeout, and provider availability.
JWT validation fails	Connector secret, HS256 verification, token header location, and expires_at within the 5-minute validity window.
Duplicate event processing	The destination must be idempotent and detect already-processed events.
Logs show no results	Select both required filters: Connector and Action. If no dates are selected, only the last 24 hours are searched.
External system misses Customer data	Confirm that the selected event payload contains the fields the external system expects; add mapping or enrichment in middleware when needed.