Skip to main content

Documentation Index

Fetch the complete documentation index at: https://empuls.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

A webhook (also called a web callback or HTTP push API) lets Empuls push real-time data to your systems as events happen — recognition awarded, survey completed, reward redeemed — without your application needing to poll for updates. This integration is particularly valuable for organizations using custom or in-house CRM systems that cannot connect through a standard native connector. Empuls supports webhook-based integration for both inbound data (pushing your data into Empuls for incentive program calculations) and outbound event notifications (Empuls pushing engagement event data to your systems).

​
When to use webhook integration

Webhook integration is the right choice when:
  • Your organization uses a custom or in-house CRM that is not part of the standard Empuls connector library
  • You have an internal system that needs to receive real-time notifications of Empuls events
  • You want to trigger downstream workflows (approval flows, payroll updates, analytics pipelines) based on Empuls activity
  • Your data lives in a proprietary database or data lake that can expose a public HTTP endpoint
Organizations without any CRM or with highly customized internal systems are prime candidates for webhook integration. Empuls fetches your data, transforms it into an acceptable format, and processes it based on templates configured in the Empuls admin platform.

​
How webhook integration works

​
Inbound: pushing data into Empuls

For inbound data, you provide a public HTTP URL endpoint where Empuls can send requests, or your system pushes data to a Empuls-provided webhook URL. Empuls:
  1. Receives the payload at the configured endpoint
  2. Transforms the raw data from your schema into Empuls-compatible format based on a pre-configured template
  3. Updates incentive programs and calculations in real time based on the new data
The schema is flexible — Empuls accommodates any JSON format and handles the transformation on its side, so your system does not need to produce Empuls-specific output.

​
Outbound: receiving Empuls events

For outbound notifications, you provide a public HTTPS endpoint in your Empuls integration configuration. Empuls sends an HTTP POST request to that URL whenever a configured event occurs.

​
Webhook events

Empuls can trigger outbound webhook notifications for the following types of events:
Event categoryExamples
RecognitionRecognition awarded, badge given, shoutout posted
RewardsPoints earned, reward redeemed, voucher issued
SurveysSurvey published, survey response submitted, survey completed
MilestonesWork anniversary reached, birthday, onboarding milestone
ProgramsIncentive payout processed, program milestone reached, leaderboard updated
User lifecycleEmployee activated, employee deactivated

​
Sample webhook payload

When Empuls triggers a webhook, it sends a POST request to your endpoint with a JSON payload. The structure varies by event type. Below is an example payload for a recognition awarded event: 
{
  "event": "recognition.awarded",
  "timestamp": "2025-04-13T10:32:00Z",
  "organization_id": "org_abc123",
  "data": {
    "recognition_id": "rec_7890xyz",
    "sender": {
      "employee_id": "emp_001",
      "name": "Priya Sharma",
      "email": "priya.sharma@yourcompany.com"
    },
    "recipient": {
      "employee_id": "emp_042",
      "name": "Arjun Mehta",
      "email": "arjun.mehta@yourcompany.com"
    },
    "badge": "Above and Beyond",
    "message": "Arjun stepped in to resolve a critical client issue over the weekend. Outstanding ownership.",
    "points_awarded": 500,
    "currency": "INR",
    "program_id": "prog_q2_recognition"
  }
}
Your endpoint should return a 200 OK response to acknowledge receipt. If Empuls does not receive a successful response, it retries the delivery.
Log all incoming webhook payloads on your side, at least during initial testing. This makes it much easier to debug mapping issues or unexpected schema variations before your integration goes into production.

​
Configuring a webhook endpoint

Setting up a webhook integration requires working with the Empuls team to define the event scope, payload format, and endpoint URL. The general process is:
1

Prepare your endpoint

Set up a publicly accessible HTTPS URL on your system that can accept POST requests. The endpoint must return a 2xx HTTP status code within a reasonable timeout to confirm receipt.
2

Contact Empuls to configure the integration

Share your endpoint URL with your Empuls account manager or contact cs@xoxoday.com. The Empuls team configures the webhook on the platform side, specifying which events trigger a notification to your endpoint.
3

Define event scope and payload template

Work with the Empuls team to specify which events should fire webhooks and whether any payload transformation or field filtering is needed.
4

Test with sample payloads

Request test events from Empuls to your endpoint. Validate that your system receives, parses, and processes the payloads correctly.
5

Monitor in production

Once live, monitor your endpoint logs for delivery failures. Empuls retries failed deliveries, but investigate failures quickly to avoid data gaps.

​
Compass Connect APIs

In addition to outbound webhooks, Empuls provides the Compass Connect API collection for organizations that want to pull data from Empuls into upstream systems rather than receive pushed events. The Compass Connect API includes 13 endpoints covering common use cases:
  • Fetch a list of active incentive campaigns
  • Retrieve incentive payout details for a user or group
  • Query leaderboard rankings
  • Access program participation data
  • Pull reward redemption records
This is useful when your system needs to display Empuls incentive data within your own application — for example, embedding a payout summary in an internal HR portal or a sales dashboard.
Custom API endpoints beyond the standard 13 Connect APIs can be developed by the Empuls engineering team for specific use cases. Contact cs@xoxoday.com to discuss feasibility.

​
Custom integration options

Beyond webhooks and Connect APIs, Empuls supports additional custom integration methods for organizations with unique requirements:
MethodDescription
Webhook / Push APIYour system pushes data to a public HTTP URL that Empuls reads
Client API fetchEmpuls fetches data directly from your API on a schedule
Database / data lake fetchEmpuls connects directly to your database or data lake
SFTP file transferScheduled batch file transfers using the SFTP protocol
Compass WebviewA standardized Empuls dashboard embedded in a browser frame within your application
All custom integrations require a qualification process with the Empuls team before setup begins. Reach out to your account manager or email cs@xoxoday.com to start the conversation.

​
Frequently asked questions

Yes. Empuls requires a publicly accessible HTTPS endpoint to ensure data is encrypted in transit. HTTP-only endpoints are not accepted.
Empuls retries failed webhook deliveries. If your endpoint is down for an extended period, contact cs@xoxoday.com to discuss recovery options for missed events.
Yes. During configuration, you specify which event types should send a notification to your endpoint. You are not required to receive all event types.
Testing is done against the Empuls staging environment. Contact your account manager to arrange test event delivery before going live.
API credentials and documentation are provided by the Empuls team. Contact cs@xoxoday.com or your account manager to request API access.