Clay logo

LeadMagic has made more than one billion API calls with Clay and won The Unstoppable Wheel award.

Recap
LeadMagicDocs

Client Webhooks

Create, list, test, and delete webhooks for batch clients. Receive real-time notifications when batches complete or items fail.

POSThttps://api.leadmagic.io/v1/batch/clients/{clientId}/webhooks
Try this endpointOpen the API playground

Endpoint Details

Manage webhooks that fire on batch events for a specific client:

  • POST /v1/batch/clients/{clientId}/webhooks: create a webhook
  • GET /v1/batch/clients/{clientId}/webhooks: list webhooks
  • DELETE /v1/batch/clients/{clientId}/webhooks/{webhookId}: delete a webhook
  • POST /v1/batch/clients/{clientId}/webhooks/{webhookId}/test: send a test event

Webhooks are delivered with an HMAC-SHA256 signature in the X-LeadMagic-Signature header. Verify this signature using your webhook's secret.

MetricValue
CostFREE

Create Webhook

url
string
required
HTTPS URL to receive webhook POSTs. SSRF-validated: must resolve to a public IP.
event_types
array
Event types to subscribe to: batch.completed, batch.failed, item.failed. Empty or omitted = all events.
webhook_id
string
UUID.
url
string
Webhook URL.
event_types
array
Subscribed events.
secret
string
HMAC signing secret. Shown once: store for signature verification.
is_active
boolean
Always true on creation.
created_at
string
ISO 8601.

The secret is returned only on creation. Use it to verify the X-LeadMagic-Signature header on incoming webhook payloads. If you lose the secret, delete and recreate the webhook.


Test Webhook

POST /v1/batch/clients/{clientId}/webhooks/{webhookId}/test sends a test payload to the webhook URL.

webhook_id
string
Webhook UUID.
sent
boolean
true if delivery was attempted.
status_code
integer
HTTP status from the webhook endpoint.
ok
boolean
Whether the endpoint returned 2xx.
error
string
Error message if delivery failed.

Webhook Payload

Webhooks deliver JSON payloads with the following structure:

Verify the X-LeadMagic-Signature header using HMAC-SHA256 with your webhook secret.


Status Codes

201

Created

200

OK

401

Unauthorized

404

Not Found

429

Rate Limit

Best Practices

Every webhook includes an X-LeadMagic-Signature header. Verify it with HMAC-SHA256 using the secret returned on creation. This confirms the payload originated from LeadMagic and was not tampered with.

Use the test endpoint to verify your webhook URL is reachable, returns the expected status code, and receives the payload format correctly before going into production.

Use event_types to filter which events trigger the webhook. For example, subscribe only to batch.failed if you only care about errors.