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.

Verifying Webhook Authenticity

You can verify the authenticity of any SnapTrade webhook by verifying the webhookSecret field contained in the body of any webhook.

Contact your customer success manager to get the correct value of this secret.

Aside from webhook secrets:

SnapTrade supports custom webhook request headers (which are useful if your webhook handler is protected by Cloudflare)
SnapTrade does not support IP whitelisting at this time

Handling Undeliverable Webhooks

When your webhook handler responds to our requests with a status code that is not 200 or 201, we mark that webhook as undelivered in our system.

We will attempt to resend an undeliverable webhook notification with an exponential backoff (starting at 30 minutes) until it is either delivered successfully, or 10 retry attempts have been made.

Webhook Types

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_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 new trades are detected in a user's account.

We send 1 webhook regardless of how many new trades are identified in your account. So if we identify 1 trade in the account, we'll send 1 webhook; and if we identify 10 trades in the account, we also only send 1 webhook.

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"
}