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.

Open Webhooks dashboard Signature Verification

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

// 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 });
}

Why raw body first?

For POST, the signature is computed over the exact bytes we sent. Frameworks that silently parse JSON before your handler runs (Express with 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.

01Create an endpoint from the dashboard. The one-time secret reveal is your only chance to copy it — store it in your secrets manager immediately.
02Choose POST or GET. POST sends configured params as JSON; GET appends configured params to the URL query string.
03Configure params. Each param can be static text or a dynamic field from the selected webhook event.
04Subscribe to event groups. Most teams begin with trader.started and signal.action.executed; narrow by referral link if you’re multi-tenant.
05Fire a test delivery. The dashboard Send Test action will sign a synthetic payload; a 2xx from your receiver confirms everything is wired.
06Return 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_disconnected

Signal lifecycle

Everything that happens to a signal and its per-trader actions.

signal.publishedsignal.invalidatedsignal.action.viewedsignal.action.executedsignal.action.failed

Need the full reference?

Per-event descriptions, supported dynamic fields, and referral-filter flags live on a dedicated page.

Open Event types

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.

trader.startedapplication/json

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

Don't retry on our behalf.

If your receiver returns 500, we'll already retry. Adding a second retry layer inside your handler usually just means the same signature gets processed twice — dedupe on X-Webhook-Event-Id and let us do the retrying.

PreviousAPI reference NextEvent types

// 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 }); }