Webhook Event Reference

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.

KeyTypeDescription
event_timeUTC Unix TimestampEvent creation date
event_typeStringIdentifies the event type which triggered the notification
event_uuidStringEvent uuid (UUIDv4)
event_detailsobjectThe payload providing event-specific data.
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>'
  }
}
KeyTypeDescription
kycStringUUID for identifying verification run for the user
outcomeStringIdentification verification status. Can be one of: passed or failed or member_failed
entityStringRegistered 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']
  }
}
KeyTypeDescription
verification_uuidStringUUID for identifying verification run for the user
entityStringRegistered user_handle
action_neededStringAction needed for the verification to continue. Values:

doc_upload - Indicates documents need to be uploaded

entity_data - Indicates entity PII needs to be reviewed and corrected

review - verification has gone into manual review by Sila, no customer action to take
reasonsArray of stringsReason tags returned from provider. See full list here

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.

KeyTypeDescription
kycStringUUID for identifying verification run for the user
outcomeStringIdentification verification status. Can be one of: pending, passed, failed, review, member_review, documents_required
entityStringRegistered user handle

📘

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
  • queued (incoming external virtual account transactions only)
KeyTypeDescription
transactionStringUUID for transaction
transaction_typeStringType of transaction. Can be one of: issue, transfer, redeem
amountIntegerAmount of funds in the transaction. The amount is equivalent to a number of cents.
outcomeStringTransaction status. Can be one of: success, failed, review, queued
entityStringRegistered user handle
processing_typeStringTransaction ACH schedule
Examples: STANDARD_ACH, SAME_DAY_ACH, INSTANT_SETTLEMENT, CARD_CKO
provider_statusStringProvider status for transaction.
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",
    "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.

KeyTypeDescription
transactionStringUUID for transaction
transaction_typeStringType of transaction: issue
amountIntegerAmount used in the transaction. Formatted in number of cents.
outcomeStringTransaction status pending_confirmation
entityStringRegistered user handle
processing_typeStringTransaction ACH schedule
Examples: STANDARD_ACH, SAME_DAY_ACH, INSTANT_SETTLEMENT, CARD_CKO
provider_statusStringProvider status for transaction.
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.

KeyTypeDescription
accountStringUUID for Bank Account Linking
outcomeStringBank Account Linking status. Can be one of: microdeposit_automatically_verified, microdeposit_manually_verified, verification_expired
entityStringRegistered user handle
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
KeyTypeDescription
account_nameStringAccount name for the registered users linked account
outcomeStringBank Account active status. Can be one of: {{account_active}}, {{account_inactive}}
entityStringRegistered user handle
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"
  }
}