REST API endpoints for registering outbound webhooks

Webhooks let you push LeadScout events to your own servers in real time. When a configured event occurs — such as a prospect’s status changing or a new appointment being created — LeadScout sends an HTTP POST to your registered URL with a signed JSON payload. You can register multiple webhooks, each with its own URL, event subscriptions, optional filters, and delivery settings.

All webhook endpoints require the admin role or higher. Requests from sales role users return 403.

List webhooks

GET /api/webhooks

Returns all active webhooks for your company, including their event registrations, ordered newest first.

curl --request GET \
  --url https://app.leadscoutapp.com/api/webhooks \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

const response = await fetch('https://app.leadscoutapp.com/api/webhooks', {
  headers: { Authorization: `Bearer ${accessToken}` },
});
const webhooks = await response.json();

Response

Returns an array of webhook objects.

number

Webhook ID.

string

Display name for this webhook.

string

The endpoint URL that receives POST requests.

string

HMAC signing secret used to verify delivery. See Verifying signatures.

number

Your company ID.

string

ISO 8601 creation timestamp.

object[]

Active event subscriptions for this webhook.

Show registration object

number

Registration ID.

string

Event name (e.g. prospect.status_changed).

object | null

Optional filter criteria applied before delivery.

number

Delivery delay in minutes (default 0).

string

automatic or manual.

string | null

Label shown on the manual trigger button, if triggerMode is manual.

Get a webhook

GET /api/webhooks/:id

Returns a single webhook with its registrations. Returns 404 if it does not exist or belongs to a different company.

Path parameters

number

required

The webhook ID.

curl --request GET \
  --url https://app.leadscoutapp.com/api/webhooks/8 \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

const response = await fetch('https://app.leadscoutapp.com/api/webhooks/8', {
  headers: { Authorization: `Bearer ${accessToken}` },
});
const webhook = await response.json();

Create a webhook

POST /api/webhooks

Request body

string

required

A human-readable name to identify this webhook. Must be at least 1 character.

string

required

The HTTPS URL that will receive POST payloads. Must be a valid URL.

string

HMAC signing secret. If you omit this, a UUID is generated automatically and returned in the response. Store it — it is not shown again.

Returns 201 with the created webhook object on success. The secretKey is included in the response body only at creation time.

curl --request POST \
  --url https://app.leadscoutapp.com/api/webhooks \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "CRM sync",
    "url": "https://hooks.yourcrm.com/leadscout"
  }'

const response = await fetch('https://app.leadscoutapp.com/api/webhooks', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'CRM sync',
    url: 'https://hooks.yourcrm.com/leadscout',
  }),
});
const webhook = await response.json();
// Store webhook.secretKey now — it is not surfaced again

Update a webhook

PATCH /api/webhooks/:id

All body fields are optional. Only the fields you send are updated.

Path parameters

number

required

The webhook ID.

Request body

string

New display name. Must be at least 1 character.

string

New destination URL. Must be a valid URL.

curl --request PATCH \
  --url https://app.leadscoutapp.com/api/webhooks/8 \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{ "url": "https://hooks.yourcrm.com/leadscout-v2" }'

const response = await fetch('https://app.leadscoutapp.com/api/webhooks/8', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ url: 'https://hooks.yourcrm.com/leadscout-v2' }),
});
const updated = await response.json();

Delete a webhook

DELETE /api/webhooks/:id

Deletes the webhook. No further deliveries are made after deletion.

Path parameters

number

required

The webhook ID.

Returns { "id": <number> } on success.

curl --request DELETE \
  --url https://app.leadscoutapp.com/api/webhooks/8 \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

await fetch('https://app.leadscoutapp.com/api/webhooks/8', {
  method: 'DELETE',
  headers: { Authorization: `Bearer ${accessToken}` },
});

Event registrations

Each webhook can subscribe to one or more events through registrations. Registrations let you fine-tune which events trigger delivery, add optional filters, delay delivery, and choose between automatic and manual trigger modes.

Registration fields

string

required

The event name to subscribe to. Must be at least 1 character.

object

Key/value criteria that the event payload must match before delivery is triggered. Pass null to receive all events of this type.

number

Integer number of minutes to wait before delivering the event. Minimum 0 (immediate). Use delays to batch or debounce rapid status changes.

string

automatic — delivered automatically when the event fires. manual — a button appears in the LeadScout UI for a rep to trigger the delivery. Defaults to automatic.

string

Label for the manual trigger button. Only used when triggerMode is manual.

Verifying signatures

LeadScout signs every delivery with an HMAC-SHA256 signature computed from the raw request body and your webhook’s secretKey. Verify the signature on your server before processing the payload to confirm the request originated from LeadScout.

Read the signature header

The signature is sent in the X-LeadScout-Signature header as a hex-encoded HMAC-SHA256 digest.

Compute the expected signature

Compute HMAC-SHA256(secretKey, rawBody) on your server using the secretKey you received when the webhook was created.

Compare signatures

Use a constant-time comparison to compare your computed signature against the header value. Reject the request if they do not match.

JavaScript

import { createHmac, timingSafeEqual } from 'crypto';

function verifySignature(rawBody, secretKey, signatureHeader) {
  const expected = createHmac('sha256', secretKey)
    .update(rawBody)
    .digest('hex');
  const actual = Buffer.from(signatureHeader, 'hex');
  const expectedBuf = Buffer.from(expected, 'hex');
  return actual.length === expectedBuf.length &&
    timingSafeEqual(actual, expectedBuf);
}

Always use a constant-time comparison (timingSafeEqual) rather than === to prevent timing attacks.

Overview

Endpoints

REST API endpoints for registering outbound webhooks

List webhooks

Response

Get a webhook

Path parameters

Create a webhook

Request body

Update a webhook

Path parameters

Request body

Delete a webhook

Path parameters

Event registrations

Registration fields

Verifying signatures

​List webhooks

​Response

​Get a webhook

​Path parameters

​Create a webhook

​Request body

​Update a webhook

​Path parameters

​Request body

​Delete a webhook

​Path parameters

​Event registrations

​Registration fields

​Verifying signatures

List webhooks

Response

Get a webhook

Path parameters

Create a webhook

Request body

Update a webhook

Path parameters

Request body

Delete a webhook

Path parameters

Event registrations

Registration fields

Verifying signatures