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

Advanced KYC kyc_status

Fires on the transition between pass/fail. Rely on kyc_action for all updates in between.

POST /webhook_event_receiver HTTP/1.1
Host: localhost:5000
Content-Type: application/json
{
  "event_time": 1594019901,
  "event_type": 'kyc_status',
  "event_uuid": '2ef7cd2b-e5f0-4fec-81cd-3be8e32c0b98',
  "event_details": {
    "kyc": '<request_uuid>',
    "outcome": 'pass or fail',
    "entity": '<user_handle>'
  }
}

Advanced KYC kyc_action

Fires on documents_required updates or review. Rely on kyc_status for pass/fail update.

POST /webhook_event_receiver HTTP/1.1
Host: localhost:5000
Content-Type: application/json
{
  "event_time": 1594019901,
  "event_type": 'kyc_action',
  "event_uuid": '2ef7cd2b-e5f0-4fec-81cd-3be8e32c0b98',
  "event_details": {
    "verification_uuid": '<verification_uuid>',
    "entity": '<user_handle>',
    "action_needed": '<action_needed>',
    "reasons": ['reason tags returned from provider']
  }
}

Classic 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" or "documents_required"

When the KYC webhook returns an outcome of "failed" or "review" or "documents_required" 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:
This webhook will trigger 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" or "documents_required" or "documents_received". Instead our Banking Operations 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
• refunded
• refund_failed

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": 'a_user_handle',
    "processing_type": "STANDARD_ACH",
    "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.

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