Skip to main content
Webhooks allow your application or agent to receive real-time push notifications when key events occur inside Leadterra, eliminating the need to poll the API. When you register a webhook, you provide an HTTPS URL and a list of event types you want to subscribe to. Leadterra will send an HTTP POST request to that URL each time one of those events fires, delivering a structured JSON payload with the full event context. You can register multiple webhooks with different URLs and event sets to fan events out to several downstream systems simultaneously.

​
Endpoint

POST /v1/webhooks

​
Authorization

All requests must include a valid API key in the Authorization header as a Bearer token. 
Authorization: Bearer sk_live_YOUR_KEY

​
Request Body

​
url
string
required
The HTTPS URL that Leadterra will POST event payloads to. Must use the https:// scheme. Plain HTTP URLs are rejected to protect the integrity of event data in transit.
​
events
array
required
An array of event type strings that this webhook should subscribe to. At least one event must be specified. Valid values are:
  • campaign.started — fires when a campaign transitions to active and begins sending.
  • message.sent — fires each time an individual outbound email is successfully handed off to the mail provider.
  • message.bounced — fires when a sent message receives a hard or soft bounce notification.
  • reply.received — fires when an inbound reply is received and classified by Leadterra.

​
Example Request

curl -X POST https://app.leadterra.co/v1/webhooks \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/leadterra",
    "events": [
      "campaign.started",
      "message.sent",
      "message.bounced",
      "reply.received"
    ]
  }'

​
Response Fields

​
id
string
The unique identifier assigned to this webhook registration. Store this value if you need to reference or delete the webhook later.
​
url
string
The HTTPS URL you registered, echoed back for confirmation.
​
events
array
The list of event type strings this webhook is subscribed to, echoed back for confirmation.
​
status
string
The current status of the webhook. A newly registered webhook always returns active.
​
createdAt
string
ISO 8601 timestamp indicating when the webhook was registered.

​
Example Response

{
  "id": "wh_456",
  "url": "https://your-app.com/webhooks/leadterra",
  "events": [
    "campaign.started",
    "message.sent",
    "message.bounced",
    "reply.received"
  ],
  "status": "active",
  "createdAt": "2025-06-10T12:00:00Z"
}

​
Webhook Payload Structure

Every event Leadterra delivers to your endpoint shares a common envelope with an event type field, a timestamp, and an data object whose shape depends on the event type. Below is a sample payload for the reply.received event — the most commonly used event in agent-driven workflows. 
{
  "event": "reply.received",
  "timestamp": "2025-06-10T14:22:00Z",
  "data": {
    "replyId": "rpl_001",
    "campaignId": "camp_123",
    "email": "ava@example.com",
    "classification": "interested",
    "threadSnippet": "Hi, this looks really interesting — can you send over more details on pricing?",
    "receivedAt": "2025-06-10T14:22:00Z"
  }
}
Your endpoint must return an HTTP 2xx status code within 10 seconds to acknowledge receipt. Any non-2xx response or a timeout is treated as a delivery failure and triggers the retry schedule described below.

​
Retry Behavior

If Leadterra does not receive a 2xx response from your endpoint, the delivery is considered failed and will be retried automatically using exponential backoff. The retry schedule is as follows:
AttemptDelay after previous attempt
1st retry30 seconds
2nd retry5 minutes
3rd retry30 minutes
4th retry2 hours
5th retry8 hours
After five failed attempts, the event is marked as permanently undelivered and no further retries are made. Leadterra does not currently emit an alert when a webhook enters a persistent failure state, so we recommend monitoring your endpoint’s availability and inspecting delivery logs in the dashboard under Settings → Webhooks. To prevent duplicate processing on your side, ensure your event handler is idempotent — use the replyId, campaignId, or other stable identifiers in the payload to detect and discard re-delivered events.
Drive agent workflows with webhook events. Registering a reply.received webhook is the most effective way to trigger an AI agent the moment a lead expresses interest. When your endpoint receives a payload with classification: "interested", you can pass the threadSnippet and lead context directly into your agent’s prompt, then use the Leadterra API to enrich the lead record or pause the sequence while a human or agent follows up — all without polling.

​
Error Codes

CodeMeaning
400Bad Request — the request body is malformed, required fields are missing, or the url does not use the https:// scheme.
401Unauthorized — your API key is missing, invalid, or revoked.
404Not Found — the requested resource could not be located.
422Unprocessable Entity — one or more events values are not recognized event types.