Events and Webhook Payloads

When configuring a webhook, you use the UI to choose which events will send payloads to your application's endpoint. Only subscribing to specific events limits the number of HTTP requests to your server. You can change the list of subscribed events anytime.

You can create webhooks that subscribe to the events listed on this page. Each webhook event includes a description of the webhook properties and an example payload.

Webhook Payload Object Common Properties

Each webhook event payload contains properties unique to the event. You can find the unique properties in the individual event type sections.

POST /webhook_event_receiver HTTP/1.1
Host: localhost:5000
Content-Type: application/json
{
  "event_time":1594018486,
  "event_type": 'kyc',
  "event_uuid": '53b851b0-a9a4-46f2-a498-19a9e3a186dc',
  "event_details": {
    "kyc": '4014fb19-15a8-4a0f-b0e2-247ac3be0bc2',
    "outcome": "pending",
    "entity": 'user'
  }
}

KYC Status Update Event

This event will trigger when a KYC verification process for a user or business associated with your application has completed with the specified outcome. kyc_update webhooks events only receive payloads for KYC verification processes which have been completed.

📘

KYC outcomes in "failed" or "review"

When the KYC webhook returns an outcome of "failed" or "review" your next step is to /check_kyc on that user to retrieve the failure or review reasons. Specifically, you're looking for the key "Tags" which has values which describe the failure or review reasons.

Each of the "Tags" values maps to list of documents that your user should provide to verify their identity in: triaging kyc failures

POST /webhook_event_receiver HTTP/1.1
Host: localhost:5000
Content-Type: application/json
{
  "event_time": 1594019901,
  "event_type": 'kyc',
  "event_uuid": '2ef7cd2b-e5f0-4fec-81cd-3be8e32c0b98',
  "event_details": {
    "kyc": '05795498-8943-455b-896f-44d18c77e8e7',
    "outcome": "pending",
    "entity": 'user'
  }
}

🚧

Review Statuses for /document uploads

For users who upload documents via Sila's /document endpoint

PASSED:
You will receive a webhook if the document(s) sufficiently verify the user's identity. Additionally, requests to /check_kyc will show that the verification status is now "passed".

FAILED:
If an entity fails KYC, then submits docs, and the docs are not sufficient to verify their identity then you will not receive a webhook back from us, and requests to /check_kyc will remain in verification status "failed" or "review". Instead our support team will reach out requesting further instructions for additional documents or better quality documents.

Transaction Status Update

This event will trigger when a transaction associated with your application has been completed with the specified outcome.

The webhook event will be triggered only if the transaction status is being updated to one of:

• success
• failed
• review
• queued (incoming external virtual account transactions only)

POST /webhook_event_receiver HTTP/1.1
Host: localhost:5000
Content-Type: application/json
{
  "event_time": 1594021059,
  "event_type": 'transaction',
  "event_uuid": 'c747c2f8-71ac-4a2e-8948-7e4090909d2d',
  "event_details": {
    "transaction": '757e3dc4-615b-400b-8cb0-7cb83bc6ff1d',
    "transaction_type": "transfer",
    "sila_amount": 1000,
    "outcome": 'success',
    "entity": 'user',
    "processing_type": "",
    "provider_status": ""
  }
}

Transaction Created

This event will trigger when you use /issue_sila with your application.

The webhook event will be triggered if the transaction status pending_confirmation.

POST /webhook_event_receiver HTTP/1.1
Host: localhost:5000
Content-Type: application/json
{
  "event_time": 1594021059,
  "event_type": 'transaction',
  "event_uuid": 'c747c2f8-71ac-4a2e-8948-7e4090909d2d',
  "event_details": {
    "transaction": '757e3dc4-615b-400b-8cb0-7cb83bc6ff1d',
    "transaction_type": "issue",
    "sila_amount": 1000,
    "outcome": 'pending_confirmation',
    "entity": 'user',
    "processing_type": "STANDARD_ACH",
    "provider_status": ""
  }
}

Bank Account Linking

This event will trigger when Plaid links a bank account to a verified entity, with plaid_token_type of public_token and link_token only.

❗️

DEPRECATED: Legacy Plaid Integration - Link Token & Plaid Public Key

If you integrated Plaid through the Sila API before July 2021, you may have a legacy integration.

Per Plaid's request, the Plaid Link token integration was deprecated on May 2022.

Please see the updated Plaid + Sila Integration documentation for the most up to date Plaid account linking process.

The bank account linking web hooks and the option to link accounts with a Plaid public token will be deprecated in May 2022. Please integrate with the Plaid processor token as soon as possible, documentation can be found here: https://plaid.com/docs/auth/partnerships/sila-money/.

Note, this event is not triggered with plaid_token_type of processor.

The webhook event will be triggered only if the account_link_status is updated to one of the following values:

• microdeposit_automatically_verified
• microdeposit_manually_verified
• verification_expired

The event will not be triggered or send the payload to the endpoint if the bank account is linked via direct bank account number entry or with the Legacy Token Plaid Instant Auth and Instant Match; these linking operations are performed synchronously, and your application receives the result at the time the Plaid Link integration is run by your app.

POST /webhook_event_receiver HTTP/1.1
Host: localhost:5000
Content-Type: application/json
{
  "event_time": 1594022112,
  "event_type": 'bank_account',
  "event_uuid": '7b6aba78-937c-4370-8914-d18465b6a18e',
  "event_details": {
    "account": 'e9cc9a41-8db3-4eb8-ad33-dd81db02f73c',
    "outcome": 'microdeposit_automatically_verified',
    "entity": 'user'
  }
}

Bank Account Unfrozen/Frozen

This event will trigger when a bank account to unfrozen/frozen.

The webhook event will be triggered only if the account_status is updated to one of the following values:

• True
• False

POST /webhook_event_receiver HTTP/1.1
Host: localhost:5000
Content-Type: application/json
{
  "event_time": 1614176827,
  "event_type": "bank_account",
  "event_uuid": "a67b5d0c-37c7-425e-bb26-939b04af98c8",
  "event_details": {
    "entity": "console_user",
    "outcome": "account_inactive",
    "account_name": "test_payment_instrument"
  }
}

Entity SMS Opt-In

This event will trigger when an entity responds to an SMS opt in message, if that entities phone number is registered with sms_opt_in key set to true.

The webhook event will be triggered only if the entity responds to the SMS opt in message.

{
  "event_time": 1594021059,
  "event_type": 'entity',
  "event_uuid": 'c747c2f8-71ac-4a2e-8948-7e4090909d2d',
  "event_details": {
    "sms_opt_in_status": true,
    "entity": 'console_user',
    "phone" : 'c747c2f8-71ac-4a2e-8948-7e4090909d2d'
  }
}