Skip to content

Webhook Test Payloads

This document describes how to test webhook integrations using test deliveries.

Overview

Testing webhook integrations requires:

  1. A webhook subscription
  2. A way to trigger test deliveries
  3. Verification that your endpoint processes them correctly

Test Subscription Endpoint

The Integration API provides a test endpoint for webhook subscriptions:

POST /api/v1/webhooks/subscriptions/{id}/test

This sends a test delivery to your webhook URL without waiting for a real event to occur.

Basic Test Request

curl -X POST <YOUR_API_URL>/api/v1/webhooks/subscriptions/123/test \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "eventType": "client.created",
    "useSamplePayload": true
  }'

Response: 

{
  "success": true,
  "statusCode": 200,
  "elapsedMs": 145,
  "responseBodyTruncated": false,
  "responseBody": "OK",
  "targetUrlUsed": "https://your-domain.com/webhooks/wlcro"
}

Test Request Parameters

Parameter Required Description
eventType No Specific event type to test (e.g., client.created)
useSamplePayload No Use SQL-generated sample data (default: true)
samplePayload No Custom payload for testing
statusOverride No Include specific status in metadata

Interpreting Test Results

Success (success: true): - Your endpoint returned 2xx status - Delivery completed within timeout - Signature verification likely passed

Failure (success: false): - Check statusCode (e.g., 401 = signature failed, 500 = endpoint error) - Review responseBody for error details - Check elapsedMs for timeout issues (> 10000ms)

Test Event Types

You can test any of the 10 v1 event types:

# Test client.created
curl -X POST .../test -d '{"eventType": "client.created"}'

# Test payment.succeeded
curl -X POST .../test -d '{"eventType": "payment.succeeded"}'

# Test payment.failed
curl -X POST .../test -d '{"eventType": "payment.failed"}'

# Test invoice.created
curl -X POST .../test -d '{"eventType": "invoice.created"}'

Available event types: - client.created - client.status_changed - lead.created - invoice.created - invoice.status_changed - payment.succeeded - payment.failed - affiliate.created - document.uploaded - agreement.signed

Sample Payloads

When useSamplePayload: true, the API generates realistic sample data. The payload structure matches real events but uses placeholder values.

Example test payload for client.created: 

{
  "id": 99999,
  "type": "client.created",
  "createdUtc": "2026-01-28T12:00:00Z",
  "companyId": 92,
  "payload": {
    "client_id": 88888,
    "first_name": "Sample",
    "last_name": "Client",
    "email": "sample@example.com",
    "phone": "+15555551234",
    "status": "Client - Active",
    "created_date": "2026-01-28T12:00:00Z"
  }
}

Sample data: - Uses recognizable placeholder values (e.g., "Sample Client") - Includes all typical fields for the event type - Safe to process in test/dev environments

Signature Verification Testing

Test deliveries include valid HMAC-SHA256 signatures using your subscription's signing secret.

Headers included: 

X-Webhook-Timestamp: 1706443200
X-Webhook-Signature: sha256=abc123def456...

Verification steps:

  1. Extract both headers
  2. Compute HMAC: hmac_sha256(signing_secret, "{timestamp}.{raw_body}")
  3. Compare with received signature (constant-time)

If signature verification fails during testing: - Confirm you're using the correct signing secret (from subscription creation) - Verify you're hashing "{timestamp}.{raw_body}" (exact format with dot) - Check you're using raw request body (before JSON parsing)

Local Development Testing

Using ngrok

  1. Start your local webhook endpoint: 

    node server.js  # or python app.py, etc.

  2. Expose with ngrok: 

    ngrok http 3000

  3. Copy the HTTPS URL (e.g., https://abc123.ngrok.io)

  4. Create webhook subscription with ngrok URL (see Webhooks API)

  5. Send test delivery using the test endpoint

  6. Check your local logs for the delivery

Using Webhook.site

For quick testing without code:

  1. Go to https://webhook.site
  2. Copy the unique URL
  3. Create subscription with webhook.site URL
  4. Send test delivery
  5. View received payload in webhook.site UI

Note: webhook.site doesn't verify signatures - use only for payload inspection.

Testing Delivery Scenarios

Successful Delivery

Test that your endpoint returns 200 and handles the payload correctly. Use the test endpoint to send a sample delivery.

Signature Verification

Test that invalid signatures are rejected:

  1. Temporarily disable signature verification in your code
  2. Send test delivery - should succeed
  3. Re-enable signature verification
  4. Send test delivery - should still succeed (signature is valid)
  5. Manually send POST with invalid signature - should fail with 401

Timeout Handling

Test that your endpoint responds quickly: - If test shows elapsedMs > 5000, optimize your endpoint - Endpoint must respond within 10 seconds - Move long operations to background queue

Error Responses

Test error handling:

  1. Temporarily make your endpoint return 500
  2. Send test delivery
  3. Expected: "success": false, "statusCode": 500
  4. Check WhiteLabelCRO will retry on non-2xx responses

Production Readiness Checklist

Before going live: - ✅ Test delivery succeeds with success: true - ✅ Signature verification passes - ✅ Response time < 5 seconds (check elapsedMs) - ✅ Endpoint returns 2xx for valid requests - ✅ Deduplication logic works (check event ID) - ✅ Error logging is in place - ✅ Monitoring/alerting configured

Troubleshooting

Test Returns success: false

Check: - statusCode: What HTTP status did your endpoint return? - responseBody: Error message from your endpoint - elapsedMs: Did request timeout (> 10000ms)?

Common causes: - 401: Signature verification failed - 500: Endpoint code error - Timeout: Endpoint too slow

Test Succeeds But Real Events Fail

Possible reasons: - Test uses sample data; real events have different field structure - Real events trigger different code paths - Volume/rate issues in production

Resolution: - Check delivery logs in WhiteLabelCRO Admin Portal for real failures - Compare test vs real payloads - Add logging to track differences

Cannot Create Test Subscription

Check: - API key has admin scope (required for test endpoint) - Subscription ID is correct - Subscription belongs to your company