> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firstwork.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Send and receive real-time event notifications with webhooks

## Overview

Firstwork supports both **outgoing webhooks** (sending events to external services) and **incoming webhooks** (receiving events from external services). Webhooks enable real-time integration with any system that supports HTTP callbacks.

## Outgoing Webhooks

### Webhook Action

The **Webhook Action** in automations sends HTTP requests to external endpoints:

| Configuration | Description                                     |
| ------------- | ----------------------------------------------- |
| URL           | Target endpoint URL                             |
| Method        | HTTP method (POST, PUT, PATCH)                  |
| Headers       | Custom HTTP headers (auth tokens, content type) |
| Body          | Request payload with variable support           |
| Timeout       | Request timeout duration                        |
| Retry Policy  | Retry configuration for failures                |

### Payload Format

Webhook payloads support [dynamic variables](/knowledge-base/dynamic-variables). Variables that read Firstwork data use [Object Graph](/knowledge-base/object-graph) paths:

```json theme={null}
{
  "event": "application_stage_changed",
  "application_id": "{{application.id}}",
  "candidate": {
    "email": "{{application.candidate.email}}",
    "name": "{{application.candidate.first_name}} {{application.candidate.last_name}}"
  },
  "stage": {
    "from": "{{transition.source_stage.name}}",
    "to": "{{transition.destination_stage.name}}"
  },
  "timestamp": "{{now}}"
}
```

### Common Outgoing Webhook Use Cases

* Notify external ATS of stage changes
* Update CRM with candidate status
* Trigger external workflows (Zapier, Make, n8n)
* Sync data with HRIS systems
* Send events to analytics platforms

## Incoming Webhooks

### Webhook Triggers

External systems can trigger Firstwork automations via incoming webhooks. Each webhook trigger gets a unique URL that external services can POST data to.

**Example payload:**

```json theme={null}
{
  "event": "background_check_complete",
  "candidate_id": "abc123",
  "result": "passed",
  "details": {
    "check_type": "criminal",
    "status": "clear"
  }
}
```

### Webhook Trigger Configuration

Each webhook trigger has:

* A unique URL that acts as the endpoint
* Associated automation that fires when called
* Input variable mapping from the webhook payload
* Authentication requirements

### Setting Up Incoming Webhooks

### Create an automation with a Webhook trigger

In the automation builder, select "Webhook" as the trigger type.

### Configure input variables

Map fields from the incoming webhook payload to automation input variables.

### Get the webhook URL

Copy the generated webhook URL with the public ID.

### Configure the external system

Point the external system's webhook/callback URL to your Firstwork webhook endpoint.

## Security

### Authentication

Incoming webhooks support:

* **API key authentication** — Bearer token in the Authorization header
* **Signature verification** — HMAC signature validation
* **IP allowlisting** — Restrict to known IP addresses

### Best Practices

Always use HTTPS for webhook URLs to encrypt data in transit.
Verify webhook signatures or tokens to ensure requests are legitimate.
Design your webhook handlers to be idempotent — the same event delivered twice should not cause duplicate actions.
Track webhook delivery status in automation execution logs and set up alerts for failures.

## Retry Policy

Outgoing webhooks are retried on failure:

* **Initial retry** — After 30 seconds
* **Second retry** — After 2 minutes
* **Third retry** — After 10 minutes
* **Final retry** — After 1 hour
* Retries stop after 4 attempts or a successful delivery

Failed webhooks are logged in the automation execution history with error details.