Migration Guide Webhooks

Understanding Webhooks v2 and Webhooks v1 (Legacy)

What's changing?

Testlify is upgrading its webhook infrastructure. The legacy webhook system (Webhooks v1) is being replaced by a new, more reliable system (Webhooks v2).

What this means for you:

• Your existing v1 endpoints will continue to receive events until 1st June 2026
• Testlify will send events to both v1 and v2 endpoints simultaneously during the transition period
• Before 1st June 2026, you must register your endpoints in Webhooks v2

We recommend migrating as early as possible.

What's new in Webhooks v2?

Testlify supports two versions of webhooks. Both are active simultaneously — Testlify sends events to endpoints registered in both versions. This article explains the difference between them and how to get started with Webhooks v2.

Navigating to Webhooks

1. Go to Settings in the top navigation bar
2. Under the Developers section in the left sidebar, click Webhooks
3. You will see two tabs: Webhooks v2 (default) and Webhooks v1 (legacy)

Webhooks v2 (Recommended)

Webhooks v2 is the new webhook system. It provides a more reliable and feature-rich experience.

Adding an Endpoint

1. Click the + Add Endpoint button on the Endpoints tab
2. Enter your Endpoint URL (e.g. https://your-app.com/webhook)
3. Optionally add a Description for the endpoint
4. Under Subscribe to events, select the specific event types you want to receive — or leave all unchecked to receive every event
5. Click Save

Tip: You can test your endpoint using Svix Play before connecting your own URL.

Available Event Types

Events are grouped into two categories:

assessment

• assessment.archived — fired when an assessment is archived
• assessment.created — fired when a new assessment is created
• assessment.deleted — fired when an assessment is deleted
• assessment.updated — fired when an assessment is updated

candidate

• candidate.completed — fired when a candidate completes an assessment
• candidate.disqualified — fired when a candidate is disqualified
• (and more — see the Event Catalog tab for the full list)

You can browse all events, their schemas, and example payloads in the Event Catalog tab.

Sample v2 Payload (assessment.created)

{
 "data": {
  "assessment": {
    "defaultLanguage": "en",
    "jobRoleId": "62f617d8ded0939121459181",
    "jobRoleName": "Backend Engineer",
    "language": "English",
    "name": "Backend Engineer",
    "title": "Backend Engineer"
  },
  "assessmentId": "69ae8827028c1d180671148e",
  "configuration": {
    "customSnapshotInterval": 120,
    "disableMobileAndTabletDevices": false,
    "enableInstructions": true,
    "enableNavigationToPreviousQuestions": true,
    "forceFullScreen": false,
    "generateAiInsight": true,
    "ipProctoringEnabled": false
  },
  "orgId": "6347ccdc9f898bd2b56cce42",
  "qualificationQuestions": [],
  "status": {
    "assessmentStatus": "DRAFT",
    "isArchived": false
  },
  "testLibraries": []
},
"event": "created",
"success": true,
"type": "assessment"
}

Logs

The Logs tab shows a full message log for all events sent to your endpoints. Each entry shows:

• Event Type (e.g. updated, created, invited)
• Message ID
• Timestamp

Click any message to inspect the full payload and see the delivery attempt status (Succeeded/Failed) per endpoint.

Activity

The Activity tab shows a Historical Delivery Attempts chart over the last 6 hours, with a summary of Successful and Failed attempt counts. Use this to monitor the health of your webhook integration at a glance.

Webhooks v1 (Legacy)

Webhooks v1 is the previous webhook system. It remains active and Testlify continues to send events to any endpoints registered here.

Existing v1 endpoints do not need to be changed immediately. However, note that the payload format differs from v2 — v1 payloads use a simpler, flatter structure.

Sample v1 Payload (updated)

{"data": {
  "name": "Backend Engineer",
  "orgId": "6347ccdc9f898bd2b56cce42",
  "access": [],
  "userId": "62b979118470b53c21e1e649",
  "grading": [
    { "max": 25, ... }
  ]
}
}

Note: v1 does not support event filtering or an event catalog. All events are delivered to all registered endpoints.

Frequently Asked Questions

1. When will Webhooks v1 be shut down?

Webhooks v1 will be discontinued on 1st June 2026. Your v1 endpoints will stop receiving events after this date.

2. Will my existing v1 webhooks stop working?

Not immediately. Testlify currently delivers events to both v1 and v2 endpoints. A migration timeline will be communicated in advance before v1 is deprecated.

3. Do I need to re-register my endpoints in v2?

Yes — your v1 endpoints are not automatically carried over to v2. You will need to add them under the Webhooks v2 tab.

4. Are the payloads the same between v1 and v2?

No. v2 payloads include richer, nested data (assessment configuration, status, test libraries, etc.) that is not present in v1. Review the Event Catalog in v2 to see the full schema for each event.

5. How do I test my v2 endpoint?

Use the Svix Play link in the Add Endpoint form to generate a test URL and inspect incoming payloads before connecting your own server.

6. Where can I see if a webhook delivery failed?

In the Logs tab, click any message to see per-endpoint delivery attempts and their status. The Activity tab shows an aggregate delivery health chart.

7. The v2 payload has less data than v1 — what if I need additional fields?

The v2 payload is intentionally leaner. If your integration requires additional data not present in the webhook payload, you can fetch it using the Testlify REST API using the assessmentId or relevant ID included in the event. This gives you full control over which data you retrieve.