How to Set Up and Use Webhooks

Who can use this feature

• Available on the Starter plan and above.

• Requires the Super Admin admin permission.

PraisePal can push real-time event notifications to an HTTPS endpoint you control. Each delivery is a JSON POST with enough context for your system to log, alert, or trigger a downstream workflow.

What this is used for

Teams typically connect a webhook to:

• Feed recognitions into reporting tools like Google Sheets or Airtable

• Forward activity to messaging platforms that accept incoming webhooks (for example, Lark)

• Trigger automations in no-code tools like Zapier or Make

• Maintain an independent audit trail of recognition and incentive activity

You can point the webhook at an endpoint your engineering team builds, or at a no-code service that accepts HTTPS webhooks.

Setting up a webhook

1. Go to Settings → Integrations.

2. Find the Webhook card.

3. Paste your HTTPS endpoint URL into the Integration Endpoint field.

4. Click Save.

PraisePal supports one webhook URL per workspace. Saving a new URL replaces the previous one. There is no verification request on save — the first real event triggers the first delivery.

There is currently no way to disconnect a webhook through the UI. To stop deliveries, replace the URL with a non-operational endpoint or contact Support.

Events and payloads

All configured events fire automatically to your endpoint — there is no way to subscribe selectively. PraisePal uses two payload shapes depending on the event family.

Recognition and comment events

Event — Fires when — `type` value in body

Comments on celebration posts (birthdays, work anniversaries) do not trigger webhooks. Self-comments are also skipped.

Headers

Every delivery includes:

Payload fields

All values are strings. The shape is identical for both recognition events.

Example: recognition

{ 
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", 
"giver_name": "Jonathan Vuk", 
"recipients": "Zelia Leong, Felix Tan", 
"type": "Recognition", 
"points": "50", 
"total_points": "100", 
"message": "Great work on the product launch!", 
"privacy": "Public", 
"company_value": "deliver-results", 
"parent_recognition_id": "", 
"link": "https://app.praisepal.com/ws/home?post_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890&post_type=recognition", 
"timestamp": "Apr 20, 2026 2:30 pm" 
}

Example: comment

{ 
"id": "f9e8d7c6-b5a4-3210-fedc-ba9876543210", 
"giver_name": "Zelia Leong", 
"recipients": "Jonathan Vuk", 
"type": "Comment", 
"points": "0", 
"total_points": "0", 
"message": "Well deserved!", 
"privacy": "Public", 
"company_value": "", 
"parent_recognition_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", 
"link": "https://app.praisepal.com/ws/home?post_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890&post_type=recognition", 
"timestamp": "Apr 20, 2026 2:45 pm" 
}

Private recognitions are included. Webhooks fire for both public and private recognitions. The privacy field tells you which kind it is, but the link opens the recognition for anyone who has it. Handle private links carefully and restrict access on your side.

Claim events

Claim payloads use a structured JSON shape. The top-level type field matches the event name.

Example: claim submitted

{ 
"type": "claim.submitted", 
"workspace_id": "00000000-0000-4000-8000-000000000001", 
"program_id": "11111111-1111-4111-8111-111111111111", 
"program_name": "Q2 learning workshop completion", 
"claim_id": "22222222-2222-4222-8222-222222222222", 
"claimant": { 
       "workspace_user_id": "33333333-3333-4333-8333-333333333333", 
       "name": "Ada Lovelace", 
       "email": "ada@example.com" 
    }, 
"proof": "Completed AWS Solutions Architect workshop on 12 Jun.", 
"timestamp": "Jun 12, 2026 3:15 pm" 
}

One-off program events

Example: one-off completed

{ 
"type": "one_off.completed", 
"program_id": "44444444-4444-4444-8444-444444444444", 
"program_name": "Q2 project completion bonus", 
"message": "Thank you for delivering the launch on time!", "points_per_recipient": 100, 
"recipients": [ { "workspace_user_id": "55555555-5555-4555-8555-555555555555", "name": "Felix Tan", "points": 100 } ] 
}

Delivery and retries

Your endpoint must respond with a 2xx status within 10 seconds. Any other response or a timeout counts as a failure.

Failed deliveries retry up to 3 attempts with exponential backoff — roughly 1 second, then 4 seconds, then 16 seconds between attempts. After the final attempt the delivery is marked as failed with no further retries.

There are no delivery logs in the PraisePal UI. Monitor success and failure on your side, using the X-PraisePal-Delivery header as a correlation ID.

Your endpoint may receive the same event more than once. Use the delivery ID or the payload id / claim_id to deduplicate.

Common issues

Webhook not firing after saving a URL — There is no test ping on save. Post a recognition in your workspace to trigger the first delivery and confirm your endpoint receives it.

Endpoint returns errors or times out — Ensure your endpoint responds within 10 seconds. If processing takes longer, acknowledge receipt immediately (return 200) and handle the work asynchronously.

Same event received more than once — PraisePal uses at-least-once delivery. Store the id from each payload and skip duplicates. The X-PraisePal-Delivery header stays the same across retry attempts for a given event.

Claim payloads look different from recognition payloads — Recognition and comment events use a flat string-keyed shape with a type of Recognition or Comment. Claim and one-off program events use structured JSON with a top-level type matching the event name (claim.submitted, one_off.completed, and so on). Branch on X-PraisePal-Event or the payload type field.

Related articles

• How to Set Up Microsoft Teams Notifications

• How to Set Up Google Chat Notifications