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

# Webhooks

> Get notified when validation events happen

Webhooks let Relaybase notify your application when a validation event happens, instead of requiring you to poll for status.

## Setting up an endpoint

<Steps>
  <Step title="Go to Webhooks in the dashboard">
    Open the **Webhooks** section of your Relaybase dashboard.
  </Step>

  <Step title="Add an endpoint">
    Click **Add Endpoint** and enter the URL you want Relaybase to send events to.
  </Step>

  <Step title="Save your webhook secret">
    You'll be given a webhook secret for that endpoint. Save it securely — you'll need it to verify incoming events.
  </Step>
</Steps>

Once created, you can manage and test your endpoints from the dashboard, or via the [Webhooks API](/api-reference/webhooks/list-webhooks).

## Event types

| Event                        | Description                                  |
| ---------------------------- | -------------------------------------------- |
| `webhook.test`               | A manually triggered test event              |
| `single.validation.started`  | A single validation request has started      |
| `single.validation.failed`   | A single validation request failed           |
| `single.validation.complete` | A single validation request completed        |
| `bulk.validation.queued`     | A bulk validation job has been queued        |
| `bulk.validation.started`    | A bulk validation job has started processing |
| `bulk.validation.progress`   | A bulk validation job has made progress      |
| `bulk.validation.completed`  | A bulk validation job completed              |
| `bulk.validation.failed`     | A bulk validation job failed                 |

## Example payloads

```json Test event theme={null}
{
  "id": "1bf3c66b-8005-423d-a430-0645f3ebd70c",
  "type": "webhook.test",
  "created_at": "2026-08-30T22:30:57.374920312Z",
  "data": {
    "message": "This is a test webhook event from RelayBase. If you received this, your webhook is working correctly."
  }
}
```

```json Bulk validation completed theme={null}
{
  "id": "a1b8dda9-b258-42fb-8c0f-f01be23bc8b5",
  "type": "bulk.validation.completed",
  "created_at": "2026-08-30T22:31:14.926317556Z",
  "data": {
    "completed_at": "2026-08-30T20:05:32Z",
    "invalid": 158,
    "job_id": "bulk_2x9p",
    "processed": 1000,
    "started_at": "2026-08-30T20:00:00Z",
    "status": "completed",
    "total_emails": 1000,
    "valid": 842
  }
}
```

```json Bulk validation failed theme={null}
{
  "id": "460461e1-ec29-4bc1-b6c3-6e5bb37ef956",
  "type": "bulk.validation.failed",
  "created_at": "2026-08-30T21:48:01.649292413Z",
  "data": {
    "error": "Validation process failed unexpectedly.",
    "job_id": "bulk_2x9p",
    "processed": 347,
    "status": "failed",
    "total_emails": 1000
  }
}
```

Every event shares the same envelope: an `id`, a `type` matching one of the event types above, a `created_at` timestamp, and a `data` object whose shape depends on the event type.

## Verifying webhook signatures

Webhook payloads are signed with SHA-256 using the secret generated for that endpoint. Use your webhook secret to verify that an incoming request genuinely came from Relaybase before trusting its contents.

<Note>
  The exact signature header and verification steps will be documented here once confirmed — for now, keep your webhook secret handy and treat any request that doesn't verify against it as untrusted.
</Note>

Webhooks are currently under development.

They are being built to work alongside the [bulk email validation](/email/bulk-validation) system, allowing Relaybase to notify your application when asynchronous validation jobs have progressed or completed, rather than requiring you to poll for job status.

Webhook functionality and its API contract will be documented here once the feature is ready for use.