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.
Key | Type | Description |
---|---|---|
event_time | UTC Unix Timestamp | Event creation date |
event_type | String | Identifies the event type which triggered the notification |
event_uuid | String | Event uuid (UUIDv4) |
event_details | object | The 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>'
}
}
Key | Type | Description |
---|---|---|
kyc | String | UUID for identifying verification run for the user |
outcome | String | Identification verification status. Can be one of: passed or failed or member_failed |
entity | String | Registered 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']
}
}
Key | Type | Description |
---|---|---|
verification_uuid | String | UUID for identifying verification run for the user |
entity | String | Registered user_handle |
action_needed | String | Action needed for the verification to continue. Values:doc_upload - Indicates documents need to be uploadedentity_data - Indicates entity PII needs to be reviewed and correctedreview - verification has gone into manual review by Sila, no customer action to take |
reasons | Array of strings | Reason 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.
Key | Type | Description |
---|---|---|
kyc | String | UUID for identifying verification run for the user |
outcome | String | Identification verification status. Can be one of: pending , passed , failed , review , member_review , documents_required |
entity | String | Registered 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
endpointPASSED:
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)
Key | Type | Description |
---|---|---|
transaction | String | UUID for transaction |
transaction_type | String | Type of transaction. Can be one of: issue, transfer, redeem |
amount | Integer | Amount of funds in the transaction. The amount is equivalent to a number of cents. |
outcome | String | Transaction status. Can be one of: success , failed , review , queued |
entity | String | Registered user handle |
processing_type | String | Transaction ACH schedule Examples: STANDARD_ACH, SAME_DAY_ACH, INSTANT_SETTLEMENT, CARD_CKO |
provider_status | String | Provider 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
.
Key | Type | Description |
---|---|---|
transaction | String | UUID for transaction |
transaction_type | String | Type of transaction: issue |
amount | Integer | Amount used in the transaction. Formatted in number of cents. |
outcome | String | Transaction status pending_confirmation |
entity | String | Registered user handle |
processing_type | String | Transaction ACH schedule Examples: STANDARD_ACH, SAME_DAY_ACH, INSTANT_SETTLEMENT, CARD_CKO |
provider_status | String | Provider 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.
Key | Type | Description |
---|---|---|
account | String | UUID for Bank Account Linking |
outcome | String | Bank Account Linking status. Can be one of: microdeposit_automatically_verified , microdeposit_manually_verified , verification_expired |
entity | String | Registered 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
Key | Type | Description |
---|---|---|
account_name | String | Account name for the registered users linked account |
outcome | String | Bank Account active status. Can be one of: {{account_active}}, {{account_inactive}} |
entity | String | Registered 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"
}
}
Updated about 1 month ago