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

# Introduction

> Webhooks introduction

## Overview

Webhooks provide real-time notifications about screening status changes in your application process. Instead of requiring you to continuously poll our API for updates, webhooks push notifications directly to your specified endpoint whenever there's a change in an applicant's screening status.

## Getting Started

### 1. Register Your Webhook Endpoint

To start receiving webhook notifications, please provide your webhook endpoint URL to: [team@cove.dev](mailto:team@cove.dev)

You will receive:

* A webhook endpoint configuration
* A webhook secret for security verification

Your endpoint should be:

* Publicly accessible over HTTPS
* Capable of handling POST requests
* Able to respond with a 200 OK status code

### 2. Security

All webhook requests will:

* Be sent over HTTPS
* Include an HMAC signature in the `X-HMAC-SIGNATURE` header
* Be signed using your webhook secret
* Have `Content-Type: application/json` header

To verify webhook authenticity, compute the HMAC signature of the raw request body using your webhook secret and compare it with the `X-HMAC-SIGNATURE` header value.

## Webhook Payload

Each webhook notification includes a JSON payload with the following structure:

```json theme={null}
{
    "time": "2025-02-03T12:26:56-05:00",
    "applicant": {
        "id": "app_123456789",
        "status": "USER_COMPLETED"
    },
    "org": {
        "id": "org_987654321"
    },
    "screening": {
        "id": "screen_123456",
        "metadata": {
            "custom_key": "custom_value"
        }
    },
    "monitoring": {
      "match": "watchlist"
    },
    "listor": {
        "id": "lst_789012"
    }
}
```

### Payload Fields

* `time`: Timestamp when the event occurred
* `applicant`: Information about the applicant
  * `id`: Unique identifier for the applicant
  * `status`: Current status of the screening (see [Status Values](/webhooks/status))
* `org`: Organization information
  * `id`: Organization identifier
* `screening`: Screening information
  * `id`: Screening identifier
  * `metadata`: Custom metadata associated with the screening
* `monitoring`: Continuous Monitoring Update
  * `match`: The check that matched
* `listor`: Listor information
  * `id`: Listor identifier

## Best Practices

1. **Verify Signatures**: Always verify the HMAC signature using your webhook secret before processing the payload.

2. **Respond Quickly**: Return a 200 OK response as soon as you receive and verify the webhook. Process the data asynchronously if needed.

3. **Handle Retries**: Your endpoint should be idempotent as the same webhook may be sent multiple times in case of delivery failures.

4. **Store Raw Payload**: Save the raw webhook data before processing it, in case you need to debug issues later.

## Testing

You can test your webhook integration by providing a test endpoint to [team@cove.dev](mailto:team@cove.dev). We'll help you simulate webhook events to verify your integration.

## Support

If you have any questions or need assistance with webhook integration, please contact:

* Email: [team@cove.dev](mailto:team@cove.dev)
* Documentation: [API Reference](https://docs.cove.dev/api-reference)

We aim to respond to all webhook-related inquiries within one business day.