Webhooks

Intro

Webhooks are notifications sent out by LocumJobsOnline when new leads are received. They allow us to send real-time notifications to web applications and reporting systems.

Once webhooks are set up, they send a request to a URL endpoint of your choice. You may set up separate endpoints for each lead event or opt to receive all lead events to the same endpoint.

Currently Supported Formats

• HTTP POST
• JSON
• Basic Authentication
• Bearer Token Authentication

Responding

Your endpoint should return an HTTP status code in the 2xx range to confirm that the data was successfully received. Any status code outside the 2xx range typically means the webhook was unable to complete the requested action.

Common causes for non-2xx response codes include incorrect or invalid URLs on the receiving endpoint, such as typos, or the receiving server rejecting URLs that exceed a certain character length.

Error Handling & Retries

Understanding how our platform handles webhook failures will help you design reliable endpoints and troubleshoot delivery issues effectively.

Response Requirements

Any response outside the 2xx range will be treated as a failure and trigger our retry mechanism.

Common Error Scenarios:

Client-Side Errors (4xx)

• 400 Bad Request: Your endpoint rejected the payload format
• 401 Unauthorized: Authentication issues with your webhook credentials
• 403 Forbidden: Your server is refusing the request
• 404 Not Found: Webhook URL is incorrect or endpoint doesn't exist
• 413 Payload Too Large: Your server cannot handle the request size
• 422 Unprocessable Entity: Your server cannot process the webhook data structure

Server-Side Errors (5xx)

• 500 Internal Server Error: Temporary issues with your server
• 502 Bad Gateway: Gateway or proxy server issues
• 503 Service Unavailable: Your server is temporarily overloaded
• 504 Gateway Timeout: Your server took too long to respond

Reference:

https://developer.mozilla.org/en-US/docs/Web/HTTP/Status

Retries

When a webhook delivery fails (non-2xx response or connection error), LocumJobsOnline automatically retries using a set retry schedule:

• Initial attempt: Immediate delivery
• Retry 1: After 1 minute
• Retry 2: After 5 minutes
• Retry 3: After 1 hour
• Retry 4: After 6 hours
• Retry 5: After 24 hours

Total attempts: 6 (1 initial + 5 retries)

After all retries are exhausted, the webhook delivery is marked as permanently failed.

Recommendations When Webhooks Fail:

• Verify your endpoint URL - Ensure the webhook URL is correct and accessible
• Check authentication - Validate that your server can verify the X-T5-Signature header & also confirm that the webhook credentials (or token) are accurate and authenticated
• Review payload handling - Ensure your endpoint can accept JSON payloads and return 2xx responses
• Test URL length limits - Some servers reject URLs that exceed character limits

• Check server error logs - Your server logs may provide insights into the error
• Inspect the .htaccess file - A misconfigured .htaccess file can cause 500 errors
• Contact your hosting provider - They can help investigate server-level issues
• Implement proper error handling - Ensure your endpoint returns 2xx responses for successful processing
• Increase server capacity - Scale your infrastructure to handle webhook volume
• Add monitoring - Track your endpoint's response times and error rates
• Consider queuing - Accept webhooks quickly and process them asynchronously

• Optimize response time - Your endpoint should respond within 30 seconds
• Return success quickly - Accept the webhook and process data asynchronously
• Implement health checks - Monitor your endpoint's availability

• Log webhook attempts - Keep records of incoming webhooks for troubleshooting
• Implement idempotency - Handle duplicate webhook deliveries gracefully
• Use monitoring tools - Set up alerts for webhook failures
• Test regularly - Use our webhook testing feature to verify your endpoint

LocumJobsOnline provides comprehensive webhook delivery monitoring:

• Delivery status - Track success/failure for each webhook attempt
• Response codes - See the exact HTTP status codes your endpoint returned
• Response messages - View error details returned by your server
• Retry history - Monitor the complete retry sequence for failed deliveries
• Payload storage - Access request/response data for debugging

Reach out to LocumJobsOnline support if you experience:

• Consistently high failure rates (>5%) despite following best practices
• Webhooks failing with valid 2xx responses
• Missing webhook deliveries for confirmed events
• Persistent authentication issues with correct signatures

Lead Events & Payloads

Recommended

TrackFive advises clients to individually support and enable each lead event trigger for the most efficient webhook experience. Given the candidate windows in effect, the previously suggested "new lead" trigger may not capture every lead event, making it a less optimal webhook solution.

Job Application Received

This event is triggered when you receive a job application.

Sample POST Payload

{
    "event": "job-application-received",
    "data": {
        "created_at": "2015-12-08T15:24:35-05:00",
        "candidate": {
            "id": 12345,
            "first_name": "John",
            "last_name": "Doe",
            "address": "1234 Example Street",
            "address2": null,
            "city": "Louisville",
            "state": "KY",
            "zip": "40210",
            "sent": "2015-12-08T15:24:35-05:00",
            "email": "johndoe@test.com",
            "phone": "1234567890",
            "license": "OD",
            "experience": "63",
            "specialties": [
                "Periodontics",
                "Neonatal",
                "Child and Adolescent Psychiatry"
            ],
            "licensed_states": [
                "PA",
                "FL",
                "NY",
                "VA",
                "Compact"
            ]
        },
        "job": {
            "id": 3,
            "title": "Job Title",
            "license": "PA",
            "specialty": "Administration",
            "city": "Lancaster",
            "state": "PA",
            "zip": "17603",
            "shift": "Night",
            "shiftType": "days",
            "shiftsPerWeek": 3,
            "hoursPerShift": 12,
            "payAmountMin": "737.00",
            "payAmountMax": "913.00",
            "payFrequency": "Hourly",
            "durationLength": 2,
            "durationUnit": "week",
            "startdate": "2025-12-06",
            "description": "Job Description",
            "requirements": "Job Requirements",
            "benefits": "Text describing the benefits for the position",
            "posted": "2025-12-06",
            "referenceNumber": "mWtvcVk0",
            "employmentType": "Locum Tenens"
        }
    }
}

Direct Application Received

This event is triggered when you receive a direct application.

Sample POST Payload

{
    "event": "direct-application-received",
    "data": {
        "created_at": "2015-12-08T15:24:35-05:00",
        "candidate": {
            "id": 12345,
            "first_name": "John",
            "last_name": "Doe",
            "address": "1234 Example Street",
            "address2": null,
            "city": "Louisville",
            "state": "KY",
            "zip": "40210",
            "sent": "2015-12-08T15:24:35-05:00",
            "email": "johndoe@test.com",
            "phone": "1234567890",
            "license": "CRNA",
            "experience": "1",
            "specialties": [
                "Allergy and Immunology",
                "Orthodontics",
                "Rad - Nuclear"
            ],
            "licensed_states": [
                "PA",
                "FL",
                "NY",
                "VA",
                "Compact"
            ]
        },
        "job": {
            "id": 7,
            "title": "Job Title",
            "license": "MD",
            "specialty": "Administration",
            "city": "Lancaster",
            "state": "PA",
            "zip": "17603",
            "shift": "Night",
            "shiftType": "days",
            "shiftsPerWeek": 3,
            "hoursPerShift": 12,
            "payAmountMin": "737.00",
            "payAmountMax": "913.00",
            "payFrequency": "Hourly",
            "durationLength": 2,
            "durationUnit": "week",
            "startdate": "2025-12-06",
            "description": "Job Description",
            "requirements": "Job Requirements",
            "benefits": "Text describing the benefits for the position",
            "posted": "2025-12-06",
            "referenceNumber": "mWtvcVk0",
            "employmentType": "Locum Tenens"
        }
    }
}

Real-Time lead Received

This event is triggered when you receive a real time lead.

Sample POST Payload

{
    "event": "real-time-lead-received",
    "data": {
        "created_at": "2015-12-08T15:24:35-05:00",
        "candidate": {
            "id": 12345,
            "first_name": "John",
            "last_name": "Doe",
            "address": "1234 Example Street",
            "address2": null,
            "city": "Louisville",
            "state": "KY",
            "zip": "40210",
            "sent": "2015-12-08T15:24:35-05:00",
            "email": "johndoe@test.com",
            "phone": "1234567890",
            "license": "DO",
            "experience": "83",
            "specialties": [
                "Interventional Radiology",
                "Trauma Surgery",
                "Urgent Care"
            ],
            "licensed_states": [
                "PA",
                "FL",
                "NY",
                "VA",
                "Compact"
            ]
        }
    }
}

Unlocked Lead Received

This event is triggered when you receive an unlocked lead.

Sample POST Payload

{
    "event": "lead-unlocked",
    "data": {
        "unlocked_at": "2015-12-08T15:24:35-05:00",
        "unlocked_by": "Smith, John",
        "candidate": {
            "id": 12345,
            "first_name": "John",
            "last_name": "Doe",
            "address": "1234 Example Street",
            "address2": null,
            "city": "Louisville",
            "state": "KY",
            "zip": "40210",
            "sent": "2015-12-08T15:24:35-05:00",
            "email": "johndoe@test.com",
            "phone": "1234567890",
            "license": "MD",
            "experience": "77",
            "specialties": [
                "Orthodontics",
                "Neonatal",
                "Optometry - Peds"
            ],
            "licensed_states": [
                "PA",
                "FL",
                "NY",
                "VA",
                "Compact"
            ]
        }
    }
}

NOT RECOMMENDED

New Lead

*WILL BE DEPRECATED* This event is triggered when you receive a new lead, including real-time leads, unlocked leads, job applicants, and direct applicants. However, it may not capture every event due to candidate windows in effect within our platform. For better coverage, we recommend opting into each specific lead event type listed above instead of relying solely on this event trigger.

Sample POST Payload

{
    "event": "new-lead",
    "lead": {
        "id": 12345,
        "first_name": "John",
        "last_name": "Doe",
        "address": "1234 Example Street",
        "address2": null,
        "city": "Louisville",
        "state": "KY",
        "zip": "40210",
        "sent": "2015-12-08T15:24:35-05:00",
        "email": "johndoe@test.com",
        "phone": "+1234567890",
        "license": "CAA",
        "experience": "31",
        "employmentType": "Locum Tenens",
        "specialties": "Perinatology",
        "contact_time": "Afternoon",
        "preferred_destinations": "New Mexico",
        "licensed_states": "West Virginia",
        "preferred_cities": "Sint vero cumque illo odio. Reprehenderit aut illum cum amet quis sed quia.",
        "license_state": "South Carolina",
        "license_date_issued": "04/04/2005",
        "license_date_expires": "12/18/1955",
        "license_investigated": "No",
        "license_investigation_details": "",
        "employment_history": [
            {
                "company": "Example Company",
                "state": "PA",
                "phone": "1234567890",
                "start_date": "2021-01-01",
                "end_date": null
            }
        ],
        "job_applications": [
            {
                "job_id": 15247,
                "title": "Example Job Title",
                "reference": "EXAMPLE12356",
                "is_direct_app": false,
                "created_at": "1980-04-17T06:49:57+00:00"
            }
        ],
        "unlocked_by": "Smith, John"
    }
}

Referral Source Structuring Recommendation

To maximize the effectiveness of your lead tracking and referral analysis via webhooks, we recommend creating separate referral sources based on the four separate lead event types

Why Structure by Lead Event Type?

• Gain more accurate insights into which programs are driving which types of engagement.
• Compare performance between the programs you're involved in
• Optimize marketing spend and outreach based on event-specific conversion trends.
• Set more granular performance KPIs per referral initiative.

Data Types & Validation

Our webhook mechanism dispatches the following types of events.

Event Types:

Default event structure:

{
    "event": "name-of-event",
    "additional-objects": "...varies by event type"
}

Here are a few data objects that are commonly used across several event types.

Candidate/Lead Data Fields:

This table outlines the standard data fields for a candidate or lead profile.

Job Fields:

Employment History Array:

DateTime Fields & Timezone Information:

• Timestamps: ISO 8601 format with timezone offset. Example: "2015-12-08T15:24:35-05:00"
• Dates: Date only in YYYY-MM-DD format. Example: "2015-12-08"

Payloads

Next, we'll provide information about the different event type payloads.

Job Application Received Payload:

Event Structure:

{
    "event": "job-application-received",
    "data": {
        "created_at": "ISO8601 timestamp",
        "candidate": {},
        "job": {}
    }
}

Root Data Fields:

Candidate Object Fields:

Uses the same structure as the Candidate/Lead Data Fields, with these values as example from the payload:

• specialties: array of strings (e.g., ["Admin/Mgmt", "Antepartum"])
• licensed_states: array of strings (e.g., ["FL"])

Job Object Fields:

Uses the same structure as the Job Data Fields.

Direct Application Received Payload:

Event Structure:

{
    "event": "direct-application-received",
    "data": {
        "created_at": "ISO8601 timestamp",
        "candidate": {},
        "job": {}
    }
}

Root Data Fields:

Candidate Object Fields:

Uses the same structure as the Candidate/Lead Data Fields.

Job Object Fields:

Uses the same structure as the Job Data Fields.

Real-Time Lead Received Payload:

Event Structure:

{
    "event": "real-time-lead-received",
    "data": {
        "created_at": "Date string",
        "candidate": {}
    }
}

Root Data Fields:

Candidate Object Fields:

Uses the same structure as the Candidate/Lead Data Fields.

Lead Unlocked Payload:

Event Structure:

{
    "event": "lead-unlocked",
    "data": {
        "candidate": {},
        "unlocked_at": "ISO8601 timestamp",
        "unlocked_by": "string"
    }
}

Root Data Fields:

Candidate Object Fields:

Uses the same structure as the Candidate/Lead Data Fields.

New Lead Payload:

Event Structure:

{
    "event": "new-lead",
    "lead": {}
}

Includes all candidate fields plus:

Mapping Requirements

Mapping our specialty and/or license lists to yours is crucial when building a webhook to ensure data consistency and accuracy. This mapping ensures that the licenses and specialties from our platform align correctly with those in your system, allowing candidates to be properly categorized and routed. Without this mapping, candidates may be added with incomplete data, leading to discrepancies and inefficient lead management.

Below is our current list of specialties and/or license types for mapping. We send the ‘Name’ value with candidate records.

License Types

Specialties

Integration Requirements

Handling Duplicate Candidates

When building webhooks or APIs to receive leads, it's essential to ensure that they are designed to handle duplicate leads—especially those that may already exist in your ATS currently attributed to another vendor.

Please ensure your system checks for existing leads before adding new ones to prevent duplicates. It is essential that existing candidates are upserted with at least the latest referral attribution from our platform, even if other candidate data remains unchanged, to accurately reflect ROI and the effectiveness of our platform.

Key Considerations:

• Check for Duplicates: Use unique identifiers (such as email or phone number) to verify if a candidate already exists in your ATS.
• Update Existing Records: If the candidate is a duplicate, update the existing record with new attribution and candidate data, rather than creating a new entry.
• Maintain Data Integrity: This ensures your candidate data remains accurate, prevents unnecessary duplication in your ATS, and preserves effective attribution for proper evaluation of your lead sources.

Next Steps for Completing Implementation

Once you have configured the webhook, you'll need to set up the endpoint URL in your BRAND account and link it to the appropriate lead events, as per your setup.

You can either share the webhook endpoint URL with your Client Success Manager or enter it directly into your account. To do this, go to the 'Agency Info' > 'Webhooks' page, then select ‘Add New Webhook.'

Enter the endpoint URL, choose the correct Authentication Type (as specified in your configuration), and select the events you want to send to that endpoint.

You have the option to create separate endpoint URLs for different event types, or you can direct all event types to the same endpoint.

After entering the details, you can test the webhook to ensure it's functioning correctly. Click on ‘Test your Webhook,' select the event you want to test, and click ‘Send Test Event.' The results will appear on the right side of the screen.

If the tests are successful, you can save the webhook endpoint URL and proceed. You're all set!