Webhook steps send data from Ashby to your external systems at a specific point in a workflow. When a step completes, Ashby sends the fields you choose to the URL you specify, so a downstream system can act on it right away, for example by opening an IT ticket to provision a laptop the moment a background check clears, instead of waiting for someone to send that request manually.

This article explains how Webhook steps work, how to add one to a workflow, and how to choose which fields to send.

Adding the step and configuring the webhook itself take two different permissions:

To use Webhooks in People Ops workflows, first create the webhook endpoint in Ashby Recruiting. Navigate to Admin > Integrations > Webhooks  and complete the following steps:

Custom HTTP headers added to your webhook configurations allow you to pass additional authentication credentials, API keys, or other identifying information that your webhook endpoint requires.

Custom headers are key-value pairs that are included with every webhook request Ashby sends to your configured endpoint. Each header has a name (e.g., X-Api-Key) and a value (e.g., your secret token).

To add custom headers to a webhook:

Once you've completed the above steps, navigate to Ashby's People Ops module and complete the following steps:

The Webhook step includes a payload builder, a flexible tool that allows you to fully define the content and structure of the JSON payload sent to your external system. With the Payload Builder, you can configure:

The Payload Builder provides access to all relevant data associated with the onboarding workflow, including:

This gives your team the flexibility to design highly customized payloads tailored to your downstream systems and automation needs.

The Payload Builder lets you construct a JSON message from any onboarding-related data inside Ashby.

Sending individual fields or objects

You can:

Field-level configuration

Each field added to the payload supports the following configuration options:

Source: Choose what populates the field:

Required vs nullable

Required fields must be resolvable; otherwise the Webhook step fails.

Nullable fields allow the webhook to send even if the value is missing (value becomes null).

JSON preview

The builder shows a live JSON preview of the payload structure.

Once a Webhook workflow step completes, Ashby marks the step as completed and displays a payload snapshot.

If a Webhook workflow step successfully completes, Ashby marks the step as Complete and no retries are attempted. Webhook responses are classified as follows:

Codes:

Ashby marks the workflow step as Failed and details are shown in the UI.

Ashby automatically retries all other non-2XX error responses up to 10 times using exponential backoff (meaning the time between retries increases after each attempt). If all retries fail:

The receiving system must respond within 10 seconds. Otherwise, Ashby considers the request failed and begins retry logic.

To ensure accurate and complete data is sent via the webhook, all required fields must be populated before the Webhook step runs in your workflow.

In addition to passing Job Consideration data through webhooks, People Ops offers three additional mechanisms for gathering employee information, depending on your team's workflow and preferred data-collection point:

One of the most flexible ways to collect field data is through a survey step in your onboarding workflow. Surveys can be configured to be completed by new hires or internal team members, depending on who the survey is assigned to within the survey step configuration.

When setting up the workflow:

Using surveys provides flexibility across teams and roles, ensures accuracy by pulling responses directly into fields, and minimizes manual data entry during onboarding.

Another way to capture field data is during workflow enrollment. When you manually enroll a new hire into an onboarding workflow, you have the option to review and populate custom fields as part of the enrollment process.

This method works best for fields that should be completed by internal team members, such as People Operations or HR coordinators, rather than by the new hire. It allows your team to confirm or add information before the workflow begins.

To configure this:

Field data can be entered directly on the employee profile at any time before the Webhook step runs.

This approach is ideal for quick edits or last-minute updates, such as correcting an address.

To do this:

All changes made here are included when the Webhook step runs.

You can sync a People Ops Employee custom field to Recruiting as an Offer custom field, so information captured during the offer process flows to the employee record automatically. This approach works best for job-specific details your recruiting team already collects on the offer, such as compensation or start date, and removes the need to re-enter that data in People Ops.

To configure this:

Once enabled, the custom field in People Ops syncs as a custom Offer field in Ashby Recruiting. From there, you can set a default value from Job data, or populate it when generating a new hire's offer.

For more on syncing Employee fields as Offer fields, see Sync Employee Custom Field as Offer FieldSync Employee Custom Field as Offer Field.

At this time, Ashby supports only outbound webhooks and cannot receive data from external systems.

Ashby automatically retries retryable errors up to 10 times. Non-retryable errors fail immediately, and the workflow step displays the relevant error information.

See Error handling & retries for additional information.

If a step is marked Failed, a user with access can manually retry directly in the UI:

We recommend:

When you save a webhook, Ashby sends a test request to your Request URL to verify that it's reachable and accepts your configuration (including any custom headers). If your endpoint returns a success response (2xx), the webhook is enabled. If the ping fails, the webhook is still saved but disabled until the issue is resolved and the webhook is saved again.