> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.100hires.com/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Use 100Hires Webhooks for Custom Integrations

# Use 100Hires Webhooks for Custom Integrations

Webhooks let your systems react to hiring events in 100Hires in real time, without polling our API on a schedule.

## What webhooks are

A webhook is an HTTPS listener you run on your side. 100Hires calls that endpoint when a subscribed event fires. Compared with polling the API every few minutes, webhooks react sooner and avoid unnecessary requests.

## Supported events

You can subscribe to hiring lifecycle events such as new applications, candidates moving between pipeline stages, and candidates being marked as hired. Refer to the OpenAPI specification at [https://api.100hires.com/v2/openapi.json](https://api.100hires.com/v2/openapi.json) for the current event types and payload schemas.

## Company-level vs per-job webhooks

100Hires supports two scopes:

- **Company-level** webhooks cover matching events across jobs in your company. Use them for integrations such as CRM sync, BI dashboards, or team notifications.
- **Per-job** webhooks cover one specific job. Use them for integrations tied to a single role.

## Setting up via API

Webhooks are included with paid plans as part of the Developer API. To get started:

1. Go to **Settings > Integrations**.
2. Find the **Developer API** section and generate an API key.
3. Complete company verification. Keys for unverified companies return `401 Unauthorized` until verification is complete.
4. Use the API key in the `Authorization: Bearer` header.
5. Register an HTTPS destination URL with the company-level or job-level webhook endpoint documented in the OpenAPI specification.

The create response returns a webhook signing secret once. Store it securely when you create the webhook.

## Payload structure

Each delivery has a JSON request body. Use the current OpenAPI specification for exact event names, fields, and example payloads.

## Delivery and reliability

The public specification does not publish a retry schedule or delivery guarantee. Return a `2xx` response quickly, process the event asynchronously, and make your handler idempotent so duplicate deliveries are safe.

## Security

Each v2 webhook has a signing secret. 100Hires signs the raw request body with HMAC-SHA256 and sends the Base64 signature in the `x-hires-signature-v2` header. Calculate the signature from the unmodified raw body and compare it before processing the event.

The create and rotate-secret responses return the active signing secret once. Company- and job-scoped rotation endpoints let you rotate a secret without replacing the webhook subscription. Follow the rotation behavior in the OpenAPI specification when switching secrets.

## Common use cases

- Sync new hires from 100Hires into your HRIS.
- Send selected application events to a team channel.
- Populate an executive dashboard with current pipeline activity.
- Mirror stage changes to your CRM.

## Testing

Before pointing webhooks at production, send them to a webhook inspector or development endpoint. Inspect the live request body and headers, verify the signature, and then test your fast `2xx` response and idempotent processing.

## Related articles

- [Developer API v2 Overview](https://help.100hires.com/en/article/developer-api-v2-overview-172n39k/)
- [MCP Server and Webhooks: Connect AI Assistants and External Systems](https://help.100hires.com/en/article/mcp-server-and-webhooks-connect-ai-assistants-and-external-systems-1tsb391/)