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

1. Go to Webhooks in the dashboard

   Open the Webhooks section of your Relaybase dashboard.

2. Add an endpoint

   Click Add Endpoint and enter the URL you want Relaybase to send events to.

3. 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.

Once created, you can manage and test your endpoints from the dashboard, or via the Webhooks API.

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

Test event

{
  "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."
  }
}

Bulk validation completed

{
  "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
  }
}

Bulk validation failed

{
  "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.

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.

Webhooks are currently under development.

They are being built to work alongside the bulk email 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.