Webhooks · Overview
Send Trading Layer events to your own systems.
Webhooks carry the state changes that matter — a trader joining, a signal going live, an execution succeeding or failing. One endpoint, one signing secret, clear event names, and a dashboard that tells you exactly what happened on every delivery.
Five minutes
Quickstart — a receiver in Next.js.
If you already understand the shape of a POST webhook, this is the core contract: read the raw body, verify, enqueue. GET endpoints use the same headers but verify the canonical query string instead of a body.
// app/api/webhooks/trading-layer/route.ts
import { NextResponse } from "next/server";
import { verifyTradingLayerWebhook } from "~/server/webhooks/verify";
import { enqueueDownstream } from "~/server/webhooks/queue";
export async function POST(req: Request) {
// IMPORTANT: read the raw body before any .json() call.
const rawBody = await req.text();
try {
verifyTradingLayerWebhook({
rawBody,
signatureHeader: req.headers.get("X-Webhook-Signature"),
secret: process.env.TRADING_LAYER_SIGNING_SECRET!,
});
} catch (err) {
return new NextResponse("invalid signature", { status: 401 });
}
const event = JSON.parse(rawBody);
// Idempotency — we may retry. Dedupe on the event id.
await enqueueDownstream(event.id, event);
return NextResponse.json({ received: true });
}express.json(), for example)
will discard whitespace and key order — verification will then fail on a valid payload. Always
route POST webhook endpoints through a raw-body path.From zero to delivering
Endpoint setup.
Each endpoint has its own signing secret, subscription list, referral-link filter, and independent delivery log. Most teams run one production endpoint and a second one pointed at a staging receiver.
- 01 Create an endpoint from the dashboard. The one-time secret reveal is your only chance to copy it — store it in your secrets manager immediately.
- 02 Choose POST or GET. POST sends configured params as JSON; GET appends configured params to the URL query string.
- 03 Configure params. Each param can be static text or a dynamic field from the selected webhook event.
- 04 Subscribe to event groups. Most teams begin with trader.started and signal.action.executed; narrow by referral link if you’re multi-tenant.
- 05 Fire a test delivery. The dashboard Send Test action will sign a synthetic payload; a 2xx from your receiver confirms everything is wired.
- 06 Return quickly (under 5 seconds). Hand any slow downstream work to your own background queue — retries penalize slow receivers the same as failing ones.
Anatomy of a delivery
Request shape.
Every delivery is signed and includes the same routing headers. POST sends JSON; GET sends the configured params as query parameters.
- Content-Type
- Present only on POST deliveries:
application/json. GET deliveries send configured params in the query string and have no body. - X-Webhook-Signature
t=<unix>,v1=<hex_hmac>. The timestamp and the HMAC-SHA256 signature, comma-separated. See signature verification.- X-Webhook-Event-Id
- Stable identifier for the underlying business event. Use it as your idempotency key.
- X-Webhook-Event-Type
- The public event name (for example, trader.started). Part of your integration contract.
Subscribe selectively
Event catalog.
Event names are stable and intended to be part of your integration contract. You can toggle groups independently from the dashboard; adding new events to a group never changes the names of existing ones.
Trader lifecycle
Onboarding and connection state for traders in your bot.
trader.startedtrader.onboardedtrader.mt5_connectedtrader.mt5_failedtrader.mt5_disconnectedSignal lifecycle
Everything that happens to a signal and its per-trader actions.
signal.publishedsignal.invalidatedsignal.action.viewedsignal.action.executedsignal.action.failedNeed the full reference?
Per-event descriptions, supported dynamic fields, and referral-filter flags live on a dedicated page.
What lands at your door
Configured params.
Every endpoint sends the params you configure. Existing endpoints without custom params keep the default envelope fields: id, type, createdAt, and data.
{
"event": "trader.started",
"telegram_id": 1880622198,
"referral_link_id": "550e8400-e29b-41d4-a716-446655440000",
"click_id": "JOPAPETUHA"
}When things go sideways
Retries and delivery log.
We retry transient failures automatically and keep the full delivery history — attempt counts, response codes, bodies, and the last error — alongside every webhook.
2xx
Delivered
Any 2xx is a success. The delivery log retains the body and status for inspection.
4xx / 5xx
Retried
Non-2xx and network errors are retried with backoff. We stop at the terminal threshold and mark the delivery as failed.
Manual
Replayed
Failed or dead deliveries can be replayed from the dashboard — the original payload and headers are preserved exactly.
X-Webhook-Event-Id and let us do the retrying.