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.
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
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 fieldsevent.idStable identifier for this webhook event.
event.typePublic event name, such as trader.started.
event.createdAtISO timestamp when the event was queued.
event.isTestTrue when the delivery came from the dashboard test action.
webhook.testMessageSynthetic message used by dashboard test deliveries.
Trader
9 fieldstrader.idInternal trader identifier.
trader.telegramIdNumeric Telegram user ID.
trader.usernameTelegram username when the user has one.
trader.firstNameTelegram first name captured from the bot profile.
trader.lastNameTelegram last name when available.
trader.isActiveWhether the trader is currently active.
trader.firstSeenAtWhen the trader was first created in Trading Layer.
trader.lastActiveAtMost recent bot activity timestamp for this trader.
trader.onboardedAtWhen onboarding was completed, if completed.
Referral
15 fieldsreferral.linkIdAttributed referral link ID for trader-scoped events.
referral.linkNameInternal name of the attributed referral link.
referral.startPayloadFixed ref_ token that identifies the referral link.
referral.rawStartPayloadFull latest Telegram /start payload.
referral.initialStartPayloadFirst Telegram /start payload captured for this trader.
referral.latestStartPayloadMost recent Telegram /start payload captured for this trader.
referral.clickIdClick ID parsed after the _cid marker in the start payload.
referral.initialClickIdFirst Click ID captured for this trader.
referral.latestClickIdMost recent Click ID captured for this trader.
referral.utmSourceUTM source configured on the attributed referral link.
referral.utmMediumUTM medium configured on the attributed referral link.
referral.utmCampaignUTM campaign configured on the attributed referral link.
referral.utmTermUTM term configured on the attributed referral link.
referral.utmContentUTM content configured on the attributed referral link.
referral.partnerCodePartner code configured on the attributed referral link.
MT5
6 fieldsmt5.statusCurrent MT5 connection status for the trader.
mt5.loginMT5 login for the connection, failed attempt, or disconnected account.
mt5.serverMT5 server for the connection, failed attempt, or disconnected account.
mt5.connectedAtWhen MT5 was connected successfully.
mt5.lastErrorLast MT5 validation error stored for this trader.
mt5.lastErrorAtWhen the last MT5 validation error happened.
Signal
20 fieldssignal.idInternal signal identifier.
signal.headlineSignal headline/title.
signal.symbolMarket symbol, such as EURUSD.
signal.directionSignal direction, such as buy or sell.
signal.statusCurrent signal status.
signal.strategySignal strategy name.
signal.providerProvider name configured for the signal.
signal.riskLevelRisk level configured for the signal.
signal.entryFixed entry price when configured.
signal.stopLossFixed stop-loss price when configured.
signal.takeProfitFixed take-profit price when configured.
signal.stopLossPercentPercent stop-loss for market-entry signals.
signal.takeProfitPercentPercent take-profit for market-entry signals.
signal.maxSlippagePercentMaximum allowed slippage for market-entry signals.
signal.additionalInstrumentsInstruments 2 and 3 of a multi-instrument signal: symbol, direction, stop-loss/take-profit/slippage percents and reference price.
signal.publishedAtWhen the signal was published.
signal.validUntilWhen the signal stops being valid.
signal.invalidatedAtWhen the signal was invalidated.
signal.invalidationReasonReason the signal was invalidated.
signal.referencePriceReference price captured for market-entry signals.
Signal action
9 fieldssignal.actionIdInternal signal-action identifier.
signal.actionTypeAction type, such as view_signal or copy_signal.
signal.actionStatusCurrent action status.
signal.riskAmountRisk amount selected by the trader.
signal.requestedVolumeRequested trade volume when available.
signal.runtimeCorrelationIdRuntime correlation ID for the trade request.
signal.executedAtWhen the signal action completed successfully.
signal.errorMessageFailure message for failed signal actions.
signal.actionMetadataStructured metadata stored on the signal action.