Recognition & Badge Event Sync

Overview

Listen to badge and shout-out (kudos) webhooks to automatically trigger recognition workflows in external systems, keeping your HRIS or performance management platform in sync with employee achievements in Workvivo.

Recognition happens in Workvivo every day: managers award badges for completing training, peers give shout-outs for going above and beyond, and automated rules assign badges when milestones are hit. But if that recognition data stays locked inside Workvivo, it can't feed into the broader systems that track employee performance, inform compensation decisions, or power rewards programmes.

Workvivo webhooks can notify an integration when badges are assigned and kudos are published. The available event data can then be mapped into an HRIS, performance management platform, rewards marketplace, or analytics system.

Value & Benefits

Keep recognition data in sync across systems. Badge assignments and shout-outs in Workvivo automatically flow to your HRIS, performance management, or rewards platform - no manual data entry or periodic exports required.

Enrich performance reviews with real-time data. Managers see a complete picture of peer recognition and badge achievements when conducting performance reviews, drawn directly from live Workvivo activity.

Power rewards and incentive programmes. Trigger reward fulfilment (gift cards, points, catalogue items) automatically when specific badges are assigned or recognition thresholds are reached.

Enable recognition analytics at scale. Feed all recognition events into your analytics platform to track recognition frequency, identify top recognisers and recipients, and measure programme health across teams and departments.

Close the loop between recognition and development. When a badge tied to a learning milestone is assigned, automatically update the employee's training record in your LMS or development platform.

Applications

HRIS recognition record sync. When a badge is assigned or a kudos is published in Workvivo, push the recognition event to the employee's profile in your HRIS (Workday, SAP SuccessFactors, BambooHR) so it appears in their performance record.

Rewards programme automation. Map specific Workvivo badges to reward tiers. When a high-value badge is assigned, automatically trigger a reward (points credit, gift card, catalogue item) in your rewards platform (Bonusly, Achievers, Vantage Circle).

Performance review enrichment. Aggregate badge and kudos data per employee over a review period and surface it in your performance management tool, giving managers concrete recognition data to reference during evaluations.

Learning completion tracking. When a badge linked to a training programme is assigned, update the employee's completion status in your LMS (Cornerstone, Docebo, Litmos) without requiring manual certification.

Recognition analytics dashboards. Stream all badge and kudos events to your BI platform to build dashboards showing recognition trends, top-recognised teams, peer-to-peer vs. manager recognition ratios, and programme adoption rates.

Manager notification workflows. When a direct report receives a badge or kudos, notify their manager via email or chat so they can acknowledge the achievement personally.

Technical Details

Webhook Configuration

See Webhooks Fundamentals for endpoint registration, request verification, retries, idempotency, and out-of-order delivery. This use case focuses on the events and processing specific to this workflow.

Webhooks are configured in Admin > Platform > Webhook Settings. The user configuring webhooks must have the Developer role in Workvivo to access this page. Click Create Webhook to add a new endpoint.

When configuring a recognition webhook, select:

Webhook Name: A name that helps identify the recognition webhook later.
Webhook URL: The HTTPS endpoint that will receive POST requests.
Authentication: No Authentication or OAuth 2.0. OAuth 2.0 adds Login URL, Client ID, Client Secret, and optional custom form parameters for the token request.
Custom Headers: Optional headers to include with each webhook request
Subscribed Events: The badge and kudos event checkboxes your integration needs. New event types are not automatically subscribed to existing webhooks.
Content Scope: Send webhooks for only public content, or send webhooks for all content when your integration must receive limited-audience kudos.

Webhook Payload Examples

Badge Assigned Event

Fired when a badge is assigned to a user. The payload includes badge and recipient data for the assignment.

{
    "action": "badge.assigned",
    "badge": {
        "id": 17,
        "title": "Example Badge",
        "description": "Example Description",
        "type": "standard",
        "value": 0,
        "rules_active": false,
        "rules_needed": "all",
        "award_msg": null,
        "award_confetti": false,
        "award_confetti_colours": [""],
        "badge_received_count": 1,
        "image": null,
        "award_image": null,
        "rules": [],
        "created_at": "2026-06-11T12:59:19Z",
        "updated_at": "2026-06-11T13:16:22Z",
        "permalink": "https://yourcompany.workvivo.com/directory/people/badges/17"
    },
    "user": {
        "id": 4,
        "external_id": null,
        "email": "kb@workvivo.com",
        "name": "Kate Banks",
        "first_name": "Kate",
        "last_name": "Banks",
        "display_name": "Kate Banks",
        "avatar_url": "https://yourcompany.workvivo.com/img/users/kate-banks.jpg",
        "job_title": "Internal Communications",
        "timezone": "Europe/Dublin",
        "locale": "en",
        "hire_date": null,
        "manager_id": 14,
        "date_of_birth": null,
        "mobile_phone": null,
        "direct_dial": null,
        "has_logged_in": true,
        "created_at": "2024-06-08T22:07:11Z",
        "permalink": "https://yourcompany.workvivo.com/directory/people/4"
    },
    "meta": {
        "id": "ge8rmw7r6z",
        "attempt": 1,
        "timestamp": 1781184169
    }
}

Kudos Published Event

Fired when a shout-out is published. The payload includes the message, the creator (giver), and the recipients (users and/or teams).

{
    "action": "kudos.published",
    "kudos": {
        "id": 22,
        "legacy_system_id": "ext-22",
        "text": "Text kudos.",
        "html": "<p>Text kudos.</p>",
        "created_at": "2023-10-15T08:00:00.000000Z",
        "audience": {
            "type": "Global"
        },
        "creator": {
            "id": 240,
            "external_id": "ja-001",
            "email": "ja@example.com",
            "name": "James Ashton",
            "first_name": "James",
            "last_name": "Ashton",
            "avatar_url": "https://example.com/img/users/james-ashton",
            "job_title": "Marketing Executive",
            "timezone": "Europe/Dublin",
            "locale": null,
            "hire_date": null,
            "date_of_birth": null,
            "mobile_phone": null,
            "direct_dial": null
        },
        "gallery": [
            {
                "url": "https://example.com/img/updates/update-image.jpg",
                "thumbnail_url": null
            }
        ],
        "attachments": [],
        "video": null,
        "goal": null,
        "recipients": {
            "users": [
                {
                    "id": 4,
                    "external_id": "4",
                    "email": "kb@workvivo.com",
                    "name": "Kate Banks",
                    "first_name": "Kate",
                    "last_name": "Banks",
                    "avatar_url": "https://example.com/img/users/kate-banks.jpg",
                    "job_title": "Internal Communications",
                    "timezone": "Europe/Dublin",
                    "locale": "en",
                    "hire_date": null,
                    "date_of_birth": null,
                    "mobile_phone": null,
                    "direct_dial": null
                }
            ],
            "teams": [
                {
                    "id": 22,
                    "external_id": null,
                    "name": "Product",
                    "avatar_url": "https://example.com/img/teams/22.jpg"
                }
            ]
        },
        "shared_post": null
    },
    "meta": {
        "id": "4m32k5ykq5",
        "attempt": 1,
        "timestamp": 1750154400
    }
}

Complementary API: Query Badge Assignments

Before using this complementary API, complete Quick Start to create an app and API key and find your Base URL and Workvivo-Id.

Use the Badge Users API to retrieve which users have been assigned a specific badge.

curl -X GET "${WORKVIVO_BASE:-https://api.workvivo.com/v1}/badges/${BADGE_ID}/users?skip=0&take=10" \
  -H "Authorization: Bearer $WORKVIVO_TOKEN" \
  -H "Workvivo-Id: $WORKVIVO_ORG_ID" \
  -H "Accept: application/json"

{
    "data": [
        {
            "user": {
                "id": 4,
                "external_id": null,
                "email": "kb@example.com",
                "name": "Kate Banks",
                "first_name": "Kate",
                "last_name": "Banks",
                "display_name": null,
                "avatar_url": "https://yourcompany.workvivo.com/img/users/kate-banks.jpg",
                "job_title": "Internal Communications",
                "timezone": null,
                "locale": null,
                "hire_date": null,
                "manager_id": 14,
                "date_of_birth": null,
                "mobile_phone": null,
                "direct_dial": null,
                "has_logged_in": true,
                "created_at": "2024-04-05T13:50:42Z",
                "permalink": "https://yourcompany.workvivo.com/directory/people/4"
            },
            "created_at": "2024-04-06T13:50:42Z"
        }
    ],
    "status": "success",
    "meta": {
        "pagination": {
            "skip": 0,
            "take": 10,
            "total_records": 1,
            "next_page": null
        }
    }
}

Webhook Delivery Behaviour

Timeouts: Workvivo has a 5-second connection timeout and a 5-second response timeout. Your endpoint must connect and respond within these windows.
Retries: If your endpoint does not return a 2xx response, Workvivo retries up to 4 additional times (5 total attempts) with exponential delay between retries.
Ordering: Events may arrive out of order. Use the event timestamp and the resource timestamps to resolve conflicts before writing to external systems.
Idempotency: Use the meta.id field to deduplicate retried deliveries - the same id is used across all retry attempts for a given event.
OAuth authentication: If OAuth 2.0 is configured, Workvivo retrieves an access token from your Login URL and sends it as an Authorization: Bearer ... header in addition to the standard webhook headers.

JavaScript Integration Example

Receive recognition events and pass the relevant Workvivo data to your HRIS or rewards platform.

import express from 'express';
import {
    hasProcessedEvent,
    markEventProcessed,
    syncBadgeToHris,
    syncKudosToHris,
    triggerReward,
} from './recognition.js';

const app = express();
app.use(express.json());

app.post('/webhooks/recognition', async (request, response) => {
    const payload = request.body;
    const eventId = payload.meta?.id;

    if (!eventId) {
        return response.status(400).json({ error: 'Missing meta.id' });
    }

    if (await hasProcessedEvent(eventId)) {
        return response.status(200).json({ status: 'already_processed' });
    }

    if (payload.action === 'badge.assigned') {
        await syncBadgeToHris(payload.badge, payload.user);
        await triggerReward(payload.badge, payload.user);
    } else if (payload.action === 'kudos.published') {
        await syncKudosToHris(payload.kudos);
    }

    await markEventProcessed(eventId);

    return response.status(200).json({ status: 'processed' });
});

app.listen(3000);

export async function hasProcessedEvent(eventId) {
    // Check your persistent deduplication store.
    return false;
}

export async function markEventProcessed(eventId) {
    // Record the Workvivo event ID after successful processing.
}

export async function syncBadgeToHris(badge, user) {
    // Store the badge assignment against the employee's HRIS profile.
}

export async function syncKudosToHris(kudos) {
    // Store the kudos against each recipient's HRIS profile.
}

export async function triggerReward(badge, user) {
    // Map eligible Workvivo badges to rewards in your rewards platform.
}