Documentation

Webhooks · Reference

Event types.

Every webhook delivery carries one of the events below. Event names are part of your integration contract — we won't rename or repurpose them. New events may be added to an existing group, but existing ones keep their semantics.

01

Quick reference

All events.

10 events across the trader and signal lifecycles. Subscribe to any combination of them per endpoint.

  • trader.started Fires when a trader opens the bot with /start.
    trader Referral-filterable
  • trader.onboarded Fires when a trader completes onboarding.
    trader Referral-filterable
  • trader.mt5_connected Fires when an MT5 account becomes connected through REST, web, or Telegram. Revalidating the same connected account does not emit another event.
    trader Referral-filterable
  • trader.mt5_failed Fires when a connection attempt fails through REST, web, or Telegram. A working connection is preserved. Validation-only API probes do not emit lifecycle events. Also fires with errorCode mt5_reauth_required when another API account sharing the same MetaTrader account connected a new password: this account must connect again with the current password.
    trader Referral-filterable
  • trader.mt5_disconnected Fires when MT5 becomes disconnected. Detaching a web or Telegram session while another frontend remains connected does not emit this event.
    trader Referral-filterable
  • signal.published Fires when a signal becomes published.
    signal
  • signal.invalidated Fires when a published signal is invalidated.
    signal
  • signal.action.viewed Fires when a trader views a signal.
    signal Referral-filterable
  • signal.action.executed Fires when a trader completes a signal action successfully.
    signal Referral-filterable
  • signal.action.failed Fires when a trader signal action fails.
    signal Referral-filterable
02

One reference, every event

All dynamic params.

The complete catalog of dynamic values you can attach to a webhook param. Fields that don't apply to a given event resolve to null on POST and are omitted on GET.

System

5 fields
Event ID event.id

Stable identifier for this webhook event.

Event Type event.type

Public event name, such as trader.started.

Event Created At event.createdAt

ISO timestamp when the event was queued.

Test Event event.isTest

True when the delivery came from the dashboard test action.

Test Message webhook.testMessage

Synthetic message used by dashboard test deliveries.

Trader

9 fields
Trader ID trader.id

Internal trader identifier.

Telegram ID trader.telegramId

Numeric Telegram user ID.

Username trader.username

Telegram username when the user has one.

First Name trader.firstName

Telegram first name captured from the bot profile.

Last Name trader.lastName

Telegram last name when available.

Active trader.isActive

Whether the trader is currently active.

First Seen At trader.firstSeenAt

When the trader was first created in Trading Layer.

Last Active At trader.lastActiveAt

Most recent bot activity timestamp for this trader.

Onboarded At trader.onboardedAt

When onboarding was completed, if completed.

Referral

15 fields
Referral Link ID referral.linkId

Attributed referral link ID for trader-scoped events.

Referral Link Name referral.linkName

Internal name of the attributed referral link.

Referral Start Payload referral.startPayload

Fixed ref_ token that identifies the referral link.

Raw Start Payload referral.rawStartPayload

Full latest Telegram /start payload.

Initial Start Payload referral.initialStartPayload

First Telegram /start payload captured for this trader.

Latest Start Payload referral.latestStartPayload

Most recent Telegram /start payload captured for this trader.

Click ID referral.clickId

Click ID parsed after the _cid marker in the start payload.

Initial Click ID referral.initialClickId

First Click ID captured for this trader.

Latest Click ID referral.latestClickId

Most recent Click ID captured for this trader.

UTM Source referral.utmSource

UTM source configured on the attributed referral link.

UTM Medium referral.utmMedium

UTM medium configured on the attributed referral link.

UTM Campaign referral.utmCampaign

UTM campaign configured on the attributed referral link.

UTM Term referral.utmTerm

UTM term configured on the attributed referral link.

UTM Content referral.utmContent

UTM content configured on the attributed referral link.

Partner Code referral.partnerCode

Partner code configured on the attributed referral link.

MT5

6 fields
MT5 Status mt5.status

Current MT5 connection status for the trader.

MT5 Login mt5.login

MT5 login for the connection, failed attempt, or disconnected account.

MT5 Server mt5.server

MT5 server for the connection, failed attempt, or disconnected account.

MT5 Connected At mt5.connectedAt

When MT5 was connected successfully.

Last MT5 Error mt5.lastError

Last MT5 validation error stored for this trader.

Last MT5 Error At mt5.lastErrorAt

When the last MT5 validation error happened.

Signal

20 fields
Signal ID signal.id

Internal signal identifier.

Signal Headline signal.headline

Signal headline/title.

Symbol signal.symbol

Market symbol, such as EURUSD.

Direction signal.direction

Signal direction, such as buy or sell.

Signal Status signal.status

Current signal status.

Strategy signal.strategy

Signal strategy name.

Provider signal.provider

Provider name configured for the signal.

Risk Level signal.riskLevel

Risk level configured for the signal.

Entry signal.entry

Fixed entry price when configured.

Stop Loss signal.stopLoss

Fixed stop-loss price when configured.

Take Profit signal.takeProfit

Fixed take-profit price when configured.

Stop Loss Percent signal.stopLossPercent

Percent stop-loss for market-entry signals.

Take Profit Percent signal.takeProfitPercent

Percent take-profit for market-entry signals.

Max Slippage Percent signal.maxSlippagePercent

Maximum allowed slippage for market-entry signals.

Additional Instruments signal.additionalInstruments

Instruments 2 and 3 of a multi-instrument signal: symbol, direction, stop-loss/take-profit/slippage percents and reference price.

Published At signal.publishedAt

When the signal was published.

Valid Until signal.validUntil

When the signal stops being valid.

Invalidated At signal.invalidatedAt

When the signal was invalidated.

Invalidation Reason signal.invalidationReason

Reason the signal was invalidated.

Reference Price signal.referencePrice

Reference price captured for market-entry signals.

Signal action

9 fields
Action ID signal.actionId

Internal signal-action identifier.

Action Type signal.actionType

Action type, such as view_signal or copy_signal.

Action Status signal.actionStatus

Current action status.

Risk Amount signal.riskAmount

Risk amount selected by the trader.

Requested Volume signal.requestedVolume

Requested trade volume when available.

Runtime Correlation ID signal.runtimeCorrelationId

Runtime correlation ID for the trade request.

Executed At signal.executedAt

When the signal action completed successfully.

Error Message signal.errorMessage

Failure message for failed signal actions.

Action Metadata signal.actionMetadata

Structured metadata stored on the signal action.