Webhooks

Getting Started

The SnapTrade API can be configured to send you webhook notifications when certain events happen in our backend.

To get started with webhooks, contact your Customer Success Manager. They will need the URL of your webhook handler for webhook notifications to begin to be sent.

The different webhook event types are outlined below.

USER_REGISTERED

Created when a new user is successfully registered through the /registerUser/ endpoint.

Example payload is below:

{
  "webhookId": "dbaee13a-1184-4677-9741-b6845e60ee3a",
  "clientId": "phjBdpKfpN",
  "eventTimestamp": "2022-05-31T11:16:54.658533+00:00",
  "userId": "qQYISR9xcmR8ZtVHNgg1lbYgSQcxafPqPW0ZbE0yaA6ham6n54",
  "eventType": "USER_REGISTERED",
  "webhookSecret": "lgCQWztweEFcHvjdLhHc"
}

CONNECTION_ATTEMPTED

Created when a user a user attempts to connect an account, will also report the result of the attempt.

Example payload is below:

{
  "webhookId": "6594d898-7377-453b-989e-03545ebde8bf",
  "clientId": "kqLsLciREm",
  "eventTimestamp": "2022-05-31T11:17:17.804976+00:00",
  "userId": "TOD1ACWHxnO9cnpq9XgNmFaRwXRMRu2taaFPpvYi6ng3uD2UN9",
  "eventType": "CONNECTION_ATTEMPTED",
  "connectionAttemptedResult": "SUCCESS",
  "brokerageId": "c8153291-0761-43a8-8ed0-4642103c2cb8",
  "webhookSecret": "PajFGRsWwxgckkOZwteW"
}

Possible values for the connectionAttemptedResult field are:

  • SUCCESS
  • AUTH_EXPIRED
  • INVALID_AUTH_CODE
  • AUTH_NOT_IN_PROGRESS
  • DUPLICATE_AUTH
  • DIFFERENT_ACCOUNT
  • UNCAUGHT_ERROR
  • INVALID_CREDENTIALS
  • INVALID_MFA_CODE
  • NO_DATA
  • IBKR_CANADA
  • LOG_FAILURE

CONNECTION_ADDED

Sent when a new brokerage connection is created using the SnapTrade connection portal.

Example payload is below.

{
  "webhookId": "7467e5e4-4b59-4514-9d04-d05dbc10dea9",
  "clientId": "cJEQQgtDIb",
  "eventTimestamp": "2022-05-31T11:13:37.269120+00:00",
  "userId": "oWbLZ3OWsO3Nt8DKJnYxM32wLLD6h6SVj0ywkDmypUlkWkqsI5",
  "eventType": "CONNECTION_ADDED",
  "brokerageId": "c8153291-0761-43a8-8ed0-4642103c2cb8",
  "brokerageAuthorizationId": "a0231bd2-9b77-4732-ba78-f9c6af6a1a62",
  "webhookSecret": "ZSDkaLCRJndeZGgeaJnV"
}

CONNECTION_DELETED

Sent when a user deletes an existing connection using the SnapTrade connection portal.

Example payload is below:

{
  "webhookId": "85a63984-6fb6-45fb-bc3b-18582a89ab3c",
  "clientId": "gxKWQEIXGS",
  "eventTimestamp": "2022-05-31T11:35:33.753881+00:00",
  "userId": "a053epCMsmII9goant5wdQH7CaT0M00HgQiRaxWnK0MncDUF2c",
  "eventType": "CONNECTION_DELETED",
  "brokerageId": "c8153291-0761-43a8-8ed0-4642103c2cb8",
  "brokerageAuthorizationId": "a0231bd2-9b77-4732-ba78-f9c6af6a1a62",
  "webhookSecret": "lbTycRhXwzVRJPovdNSN",
  "brokerageAuthorizationId": "183d507c-d531-4e83-8315-a5cc5bc9cbfd"
}

CONNECTION_BROKEN

Sent when a user's connection is broken for some reason, usually an inability to handshake with the brokerage's API.

Example payload is below:

{
  "webhookId": "434d23af-5f89-44f8-9415-5029557e64c7",
  "clientId": "yLNANjmwau",
  "eventTimestamp": "2022-05-31T11:37:50.590720+00:00",
  "userId": "DbjLqtPsj6G1MlDLtZaps4YhtckD0jWOuLQjl6GPW4FmpUa8eo",
  "eventType": "CONNECTION_BROKEN",
  "webhookSecret": "SCNsZYmJcuXRiznplDdL",
  "brokerageAuthorizationId": "dc90a844-367b-4120-8b56-21040bfa6525"
}

CONNECTION_FIXED

Sent when a broken connection is fixed.

Example payload is below:

{
  "webhookId": "ae73c055-2308-4de4-bf0e-d828bbac8c91",
  "clientId": "BVmifPEScc",
  "eventTimestamp": "2022-05-31T11:52:26.803063+00:00",
  "userId": "EKDO7W7YSWEZkOZUN5v1iMGF7ipEmOGjc6bMEm89y6vCrtnebH",
  "eventType": "CONNECTION_FIXED",
  "webhookSecret": "zNKlROkqSEXjXBxfTsAu",
  "brokerageAuthorizationId": "5e942e13-2b39-47b2-b524-858b9d9849ed"
}

CONNECTION_UPDATED

Sent when a brokerage connection is updated.

Example payload is below:

{
  "webhookId": "57a293e4-f7eb-49ad-92e2-80ac16e01af7",
  "clientId": "IZtBuuKXEA",
  "eventTimestamp": "2022-05-31T11:53:09.437310+00:00",
  "userId": "sXQQcRdQEmGSMizpv45gBlBANBeCWgEn9uSmLlEpa1YsZ7oAW8",
  "eventType": "CONNECTION_UPDATED",
  "webhookSecret": "oHdlCBoExKtosDtTLVDc",
  "brokerageAuthorizationId": "7ed55083-7128-46ff-9317-43cd788f43ff"
}

CONNECTION_FAILED

Sent when a user attempt to connect to a brokerage has failed.

Example payload is below:

{
  "webhookId": "57a293e4-f7eb-49ad-92e2-80ac16e01af7",
  "clientId": "IZtBuuKXEA",
  "eventTimestamp": "2022-05-31T11:53:09.437310+00:00",
  "userId": "sXQQcRdQEmGSMizpv45gBlBANBeCWgEn9uSmLlEpa1YsZ7oAW8",
  "eventType": "CONNECTION_FAILED",
  "webhookSecret": "oHdlCBoExKtosDtTLVDc"
}

NEW_ACCOUNT_AVAILABLE

Created when a new account is detected through your brokerage connection.

Example payload is below:

{
  "webhookId": "6fe03e8c-201a-4c3f-92d0-acb825fc89cf",
  "clientId": "SjWLDemQUF",
  "eventTimestamp": "2022-05-31T12:37:18.630476+00:00",
  "userId": "hmznAjmLezKPaSnLIiNQweSGsf7MIlEvm9dcTao3gwjgBtulLK",
  "eventType": "NEW_ACCOUNT_AVAILABLE",
  "webhookSecret": "HZRnYEhLPgwyUXitkJBd",
  "accountId": "ec20134b-72e7-4e72-9b4c-9c7ddd1c479c",
  "brokerageAuthorizationId": "795de4e6-260e-45b3-815b-8f601c4cf448"
}

ACCOUNT_UPDATED

Created when an existing account is updated in some way.

Example payload is below:

{
  "webhookId": "2a4d39a9-6b96-4c81-bcd0-decdb19ecb8d",
  "clientId": "ksZjCOKakA",
  "eventTimestamp": "2022-05-31T12:06:39.808317+00:00",
  "userId": "zbGKzPh9tUXP1QpW6gaPg4rxY3EgyucTxRabmPNCH2jWWQFgfu",
  "eventType": "ACCOUNT_UPDATED",
  "webhookSecret": "pYpBWpLMkvelHcVArQPo",
  "accountId": "e7c75b0c-1f0b-4145-a982-3b66752192f1",
  "brokerageAuthorizationId": "18301c53-b47e-4753-934f-4dd84bc5d320"
}

ACCOUNT_REMOVED

Created when an account is removed.

Example payload is below:

{
  "webhookId": "b78b1751-4b95-466b-84e9-17ce73541cd3",
  "clientId": "sqAJaSZbpM",
  "eventTimestamp": "2022-05-31T12:38:06.238383+00:00",
  "userId": "UCr46KnnToqvSkJW3PJu2CyLaS4QXPENak7Bp3fpEurfPTjLHR",
  "eventType": "ACCOUNT_REMOVED",
  "webhookSecret": "UaJRrbfcgAVYGutotJWg",
  "accountId": "d4ecbcde-8f98-48d2-928d-5aeeb5d63fb6",
  "brokerageAuthorizationId": "27cd7f6b-fd29-4ed6-a3fb-fd32d4cd5832"
}

ACCOUNT_HOLDINGS_UPDATED

Created when account holdings are updated.

Example payload is below:

{
  "webhookId": "c4403103-42bb-435a-9ea3-defde2e2fb17",
  "clientId": "YDEgJnFFqT",
  "eventTimestamp": "2022-05-31T12:39:26.021996+00:00",
  "userId": "zIy60lci0hukBkyD8c3OPcpMxbWA9JZpf9qhPMc9UCCSAyj6he",
  "eventType": "ACCOUNT_HOLDINGS_UPDATED",
  "webhookSecret": "YdHBEzXWqMSKterLMvCM",
  "accountId": "55ede4ef-0997-4578-a37b-f4bb0f2211d3",
  "brokerageAuthorizationId": "c0874ca2-5046-4a15-b114-b45615cc2872"
}

ACCOUNT_TRANSACTIONS_INITIAL_UPDATE

Created the first time that we collect transactions data from a brokerage account.

Example payload is below:

{
  "webhookId": "aa7a7d5a-4a12-40df-a329-feedc738eee9",
  "clientId": "rmCZBUGAXP",
  "eventTimestamp": "2022-05-31T12:39:47.182403+00:00",
  "userId": "7jN22b2AWHMOqOeujjaiU5kKOM8iITt11ENcUMftx6LBg9GTn2",
  "eventType": "ACCOUNT_TRANSACTIONS_INITIAL_UPDATE",
  "webhookSecret": "gQNuZIBwPYUVAsXvCfOA",
  "accountId": "d9f55a48-5dc6-4100-acee-24e5dfd8ec26",
  "brokerageAuthorizationId": "d28affae-f918-4ecd-8128-e5438e861706"
}

ACCOUNT_TRANSACTIONS_UPDATED

Created when account transactions are updated.

Example payload is below:

{
  "webhookId": "4eb13e1c-5778-44c2-968d-813d81cb73a1",
  "clientId": "JELZRJPqui",
  "eventTimestamp": "2022-05-31T12:40:05.944481+00:00",
  "userId": "4XTxw0mZhffRCdrgPHBG1VqdklkVJdEz5Uor0hq29hwPYlLS7s",
  "eventType": "ACCOUNT_TRANSACTIONS_UPDATED",
  "webhookSecret": "DDAVBuPPGgqwADXgbcOE",
  "accountId": "6e30be12-4ab0-4ec0-8d4d-0dfdce509e36",
  "brokerageAuthorizationId": "8105b33e-3dd6-4189-b93e-31ccaa9d3b69"
}

TRADES_PLACED

Gets sent when a new trade is detected in a user's account. Please contact us in order to receive these webhooks as they are disabled by default.

Example payload is below:

{
  "webhookId": "c4403103-42bb-435a-9ea3-defde2e2fb17",
  "clientId": "YDEgJnFFqT",
  "eventTimestamp": "2022-05-31T12:39:26.021996+00:00",
  "userId": "zIy60lci0hukBkyD8c3OPcpMxbWA9JZpf9qhPMc9UCCSAyj6he",
  "eventType": "TRADES_PLACED",
  "webhookSecret": "YdHBEzXWqMSKterLMvCM",
  "accountId": "55ede4ef-0997-4578-a37b-f4bb0f2211d3",
  "brokerageAuthorizationId": "c0874ca2-5046-4a15-b114-b45615cc2872"
}