---
title: Workflow Steps: Webhooks
slug: workflow-steps-webhooks
createdAt: 2026-09-11T08:15:25.131Z
---

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.

:::hint{type="warning"}
Ashby's People Ops module is currently available through restricted early access. The following documentation is provided for design partners participating in that program.
:::

# Permissions and access

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

- Configure the webhook in Ashby Recruiting: you need Organization Admin access, because webhooks live in **Admin > Integrations > **[Webhooks](https://app.ashbyhq.com/admin/api/webhooks/create).
- Add a Webhook step to a workflow: you need view and edit access to that workflow. Your permission set grants this access to either all workflows or specific workflows.

:::hint{type="info"}
Learn more about Ashby's People Ops permission sets: [Configure Permission Sets](docId:7apvU1qei2QWWO4SL6UOI).
:::

# Setup instructions

:::hint{type="info"}
See Ashby's [Developer Guide on Setting up Webhooks](https://developers.ashbyhq.com/docs/setting-up-webhooks) for additional details.
:::

## Configure the webhook in Ashby Recruiting

To use Webhooks in People Ops workflows, first create the webhook endpoint in Ashby Recruiting. Navigate to **Admin > Integrations > **[Webhooks](https://app.ashbyhq.com/admin/api/webhooks/create) and complete the following steps:

1. Select `+ New` in the upper right corner.
2. Enter a Title (this helps you find it later).
3. Select `Workflow Step` as the webhook type.
4. Enter the URL of the external system's endpoint.
5. Optionally add a Secret Token for request verification.
6. Select `Save`.

![The screenshot shows the screen to configure a webhook step.](https://api.archbee.com/api/optimize/0p8tQ--ZZOxRtkVp6Qr-e/JdiC9MDub99453taygP5O_989a0af8-05c9-4814-b970-f7e6881eeba6.png)

### Webhook custom headers

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:

1. Configure the webhook as described in [Configure the webhook in Ashby Recruiting](docId\:BTj4zkHQkZLyR5YvIUK00).
2. Under **Custom headers**, select `Add Header`.

::Image[]{src="https://api.archbee.com/api/optimize/0p8tQ--ZZOxRtkVp6Qr-e/kyoBtaB9qv70q5MfvE71V_screenshot2026-03-03at72807pm.png" size="100" alt="The screenshot shows the screen to configure a webhook step with the + Add header button highlighted." isUploading="false" width="780" height="808" darkWidth="780" darkHeight="808" showCaption="false" indent="1"}

3. Enter a header name and value. Header values are encrypted at rest and are not displayed in the UI after they are saved.
   - Header names must start with X- (e.g., X-Api-Key). This follows HTTP conventions for custom/non-standard headers.
   - Custom header limitations:
     - Header names: Maximum 128 characters.
     - Header values: Maximum 2,000 characters.
     - Header values must contain only printable ASCII characters (no control characters or non-ASCII characters).
4. Select `Save`. Your custom headers are now included in all webhook requests to this endpoint.

::Image[]{src="https://slabstatic.com/prod/assets/l73blu9g/post/istuamx8/preimages/fStcbPonPNxUPg8TWXltjO6A.png?jwt=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJodHRwczovL3NsYWJzdGF0aWMuY29tIiwiZXhwIjoxNzcyNTg2OTg3LCJpYXQiOjE3NzI1Nzk3ODcsImlzcyI6Imh0dHBzOi8vYXBwLnNsYWIuY29tIiwianRpIjoiMzJjbmZyNjM2N29uZDc0NDhrcDFtNnMzIiwibmJmIjoxNzcyNTc5Nzg3LCJwYXRoIjoicHJvZC9hc3NldHMvbDczYmx1OWcvcG9zdC9pc3R1YW14OCJ9.Kjnmc101dX8KQPixLxxlkl-1UKuBLcEIxgT_h3dwJ0SySvNs2byOQz-MSQoMpzLK4PUA4EQpDVQy_9969YRUmwAN5xHedTiJ46kkP78HMvZx3DLyj68Q18ngVOwIzN-zr7PgEi3Y8cY8DwWET1kAiA5MKkOcgr88l6xJuOOP7YfV2zhizHWpQPJePmU_IDENVwpis1_PbcgmxHKYfmsNa0d9nevCYSiUh9A9Udx0xGY9e8479EkDvTQnKsdKE6MtelErsNyE-oXpyTzwI1HDYu7IJ6CmtEFjeTQzUbg0geKKOurjvWdg7r7T44B6eqBBJaaPujFJ9AwP55O-yqzuJA" size="100" alt="Screenshot of custom headers configuration" isUploading="false" width="390" height="164" darkWidth="390" darkHeight="164" showCaption="false" indent="1"}

:::hint{type="info"}
You can add up to five custom headers. To remove one, select the trash icon to the right of the header.
:::

## Adding a Webhook step

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

1. Open the workflow, select `Edit Workflow Template`, then select `Add Step` in the appropriate section.
2. Select `Webhook` from the step type dropdown.
3. [Configure the payload](docId\:BTj4zkHQkZLyR5YvIUK00) as outlined below.
4. Set the step's delay, filter, and dependencies. See [Configure your Workflow Steps](docId:58jSO5IfDvlsM2Ld-Bb7p) for details.
5. Publish your changes.

![Screenshot of the options to add a step with the Webhook option highlighted.](https://api.archbee.com/api/optimize/0p8tQ--ZZOxRtkVp6Qr-e/fyXQaw5pJxDp6GgOMZgcq_screenshot2026-08-12at54433pm.png)

## Configure the payload

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 structure and hierarchy of the outgoing JSON body
- Which fields from Ashby should populate each value
- Fixed (constant) values that are always sent
- Whether each field is required or nullable
- Nested objects for more complex payloads

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

- Employee profile fields (standard and custom)
- Job Consideration fields (standard and custom)
- Workflow fields (status, start date, step information including survey answers

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

![A screenshot of the payload builder and a JSON preview.](https://api.archbee.com/api/optimize/0p8tQ--ZZOxRtkVp6Qr-e/myTnlh95NS3qpVpQJuWB7_image.png)

### The Payload Builder

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

**Sending individual fields or objects**

You can:

- Send single fields like `employee.email`, `employee.startDate`
- Send objects such as an entire employee or job object
- Compose hybrid nested structures

::Image[]{src="https://api.archbee.com/api/optimize/0p8tQ--ZZOxRtkVp6Qr-e/cBv19SPfgFrdVV_GELLOW_workflow-steps-webhooks-archbee-document-2026-10-26-at-31321-pm.jpg" size="60" isUploading="false" width="786" height="466" darkWidth="786" darkHeight="466" alt="The screenshot shows a completed payload template." showCaption="false"}

**Field-level configuration**

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

**Source:** Choose what populates the field:

- Existing field value (e.g., Employee Manager, Business Unit)

![The screenshot shows a field with the source menu open and set to Field Value](https://api.archbee.com/api/optimize/0p8tQ--ZZOxRtkVp6Qr-e/IIspc8CEcIPqQyMrGS7DD_6d848ac2-46a4-4441-9ac3-a9b4cf513f59.png)

- Constant (fixed value sent for every employee)

![The screenshot shows a field with the Source menu open with the value set to Constant.](https://api.archbee.com/api/optimize/0p8tQ--ZZOxRtkVp6Qr-e/PTqDu3A7XyJ9_G2dimTHe_2a79777a-440f-4b25-8051-32fb5dcc0940.png)

**Required vs nullable**

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

![Screenshot 2025-11-26 at 12.26.35 PM](https://api.archbee.com/api/optimize/0p8tQ--ZZOxRtkVp6Qr-e/HbMXUkOaKVk4ShUNeaJTw_screenshot2025-11-26at122635pm.png)

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

![Screenshot 2025-11-26 at 12.26.46 PM](https://api.archbee.com/api/optimize/0p8tQ--ZZOxRtkVp6Qr-e/w60Pv-M8m50UHiZ8fWyT8_screenshot2025-11-26at122646pm.png)

**JSON preview**

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

![image.png](https://api.archbee.com/api/optimize/0p8tQ--ZZOxRtkVp6Qr-e/X6019V3KcRJqN6x5QIEZR_image-1.png)

# What happens when a webhook sends

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

:::hint{type="danger"}
The snapshot shows the current field values, not the exact payload that was sent. Ashby does not store the potentially sensitive data that was sent to the external system.
:::

# Error handling & retries

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

## Non-recoverable errors (not retried)

Codes:

- **401** Unauthorized
- **403** Forbidden
- **404** Not Found
- **405** Method Not Allowed
- **410** Gone
- **413** Payload Too Large

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

## Errors that trigger automatic retries

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:

- Ashby marks the step as Failed.

![The screenshot shows the Issues option that you can hover over to view workflow issues.](https://api.archbee.com/api/optimize/0p8tQ--ZZOxRtkVp6Qr-e/cbK9iyiRLEqFIh2szLLJx_image-2.png)

- A user with access can manually retry from the UI. To do this, click `Retry` within the Webhook step popover.

![image.png](https://api.archbee.com/api/optimize/0p8tQ--ZZOxRtkVp6Qr-e/6jtMGbDdOQg_ggCb23m8q_04a74e11-5b4b-4444-b018-cd9a593a2b2e.png)

## Timeout requirement

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

# Managing webhook data collection in People Ops

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:

## Through a Survey step

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:

1. Add a survey step to your workflow and select the relevant recipient. This can be the new hire or another employee or a custom role (for example, a People Ops Coordinator).
2. Configure your survey questions.
3. If you did not configure survey responses to be included as part of your webhook payload, you can use Ashby's [Form Field Connectors](docId\:hDnnC9Znj8gSR0fjXUyQN) to link the question directly to the corresponding custom field. When the respondant completes the survey, their answers automatically populate the linked employee custom field.

![image.png](https://api.archbee.com/api/optimize/0p8tQ--ZZOxRtkVp6Qr-e/Iwp1fDuxpYAZgWWFKHI7N_image-3.png)

:::hint{type="info"}
You can create multiple surveys if data needs to come from different sources, for instance, one survey for the new hire to provide personal details and another for the People Ops team to complete company or job-specific information.

You can also send survey responses collected in the workflow via the webhook 
:::

3. To ensure all data is collected before the Webhook step, make survey completion a dependency for the Webhook step. This ensures the integration doesn't run until all required surveys have been submitted and mapped fields are complete.

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

## During workflow enrollment

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:

1. Enroll a new hire in a workflow.
2. During the **Review Custom Fields** step, you see the applicable custom employee fields.
3. Enter the necessary details before launching the workflow.

![The screenshot shows the Review Employee and Enroll in workflow step where you can enter information into custom fields.](https://api.archbee.com/api/optimize/0p8tQ--ZZOxRtkVp6Qr-e/GWa3aWgdWlkktw-eFr1lY_image-4.png)

:::hint{type="danger"}
If you use automations to auto-enroll new hires without review, this manual enrollment step is skipped.
:::

## On the employee profile

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:

1. Navigate to the employee's profile in People Ops.
2. Navigate to the **Custom Fields** section of the employee's profile and locate the applicable field.
3. Enter or update the information as needed.

![Screenshot 2025-11-05 at 9.18.36 PM](https://api.archbee.com/api/optimize/0p8tQ--ZZOxRtkVp6Qr-e/VwgvrDh_tt4sfzLGMYTir_screenshot2025-11-05at91836pm.png)

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

## By syncing as an Offer field

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:

1. Navigate to **Admin > **[Custom Fields](https://app.ashbyhq.com/people-ops/admin/custom-fields/employee).
2. Locate the applicable Employee field.
3. Enable the `Sync as Offer Field?` toggle for that field.

![A custom field with the Sync as Offer Field option checked.](https://api.archbee.com/api/optimize/0p8tQ--ZZOxRtkVp6Qr-e/06rzEL62mFSOioRbvXnoy_47540206-330b-47d4-b2bd-c99a0d7cc897.png)

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 Field](docId\:v6azQjt9W6mQtIJcFXGW1).

# FAQ

### Can other systems send information back into Ashby via webhooks?

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

### What happens if the webhook returns an error?

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](docId\:BTj4zkHQkZLyR5YvIUK00) for additional information.

### Can I manually retry a Webhook step?

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

![image.pngA screenshot showing the failed webhook step with the option to retry.](https://api.archbee.com/api/optimize/0p8tQ--ZZOxRtkVp6Qr-e/kxVvIz3wQSPCKDDrA_eAD_image-5.png)

### How can I test my webhook?

We recommend:

- Hiring a test employee in Ashby Recruiting
- Enrolling them in an onboarding workflow
- Using a test endpoint or a webhook viewer tool like RequestBin

### What does the warning: "A 'Ping' webhook will be sent to your Request URL before the webhook is enabled" mean?

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.