Skip to main content

​
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:
ConfigurationDescription
URLTarget endpoint URL
MethodHTTP method (POST, PUT, PATCH)
HeadersCustom HTTP headers (auth tokens, content type)
BodyRequest payload with variable support
TimeoutRequest timeout duration
Retry PolicyRetry configuration for failures

​
Payload Format

Webhook payloads support Object Graph variables: 
{
  "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: 
{
  "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

1

Create an automation with a Webhook trigger

In the automation builder, select “Webhook” as the trigger type.
2

Configure input variables

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

Get the webhook URL

Copy the generated webhook URL with the public ID.
4

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.