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 to 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>',
    "entity": '<user_handle>',
    "outcome": 'passed',
    "wallet_id": '<wallet_uuid'>
  }
}

Key	Type	Description
kyc	String	UUID for identifying verification run for the user
entity	String	Registered user_handle
outcome	String	Identification verification status. Can be one of: `passed` or `failed` or `member_failed`
wallet_id	String	The payment instrument UUID for the entity's default wallet.

Advanced KYC kyc_action

Fires on verification_status transition to documents_required 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": {
    "entity": '<user_handle>',
    "reasons": ['reason strings returned from provider', 'an additonal reason string', 'another possible reason string'],
    "action_needed": null,
    "verification_uuid": '<verification_uuid>',
  }
}

Key	Type	Description
entity	String	Registered user_handle
reasons	Array of strings	Reasons returned from provider.
action_needed	null	Not relevant to Priority - will be `null`
verification_uuid	String	UUID for identifying verification run for the user

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

Fires when a transaction status is updated to one of the following:

success
failed
review
refunded
refund_failed

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`, `refunded`, `refund_failed`
entity	String	Handle for the entity which initiated the transaction
processing_type	String	One of: `STANDARD_ACH`, `SAME_DAY_ACH`, `CARD_CKO`, `RTP`, `FedNow`
provider_status	String	Provider status for transaction. Only applicable where outcome is not one of: `success`, `failed`, `review`, e.g., `refunded`, as this is a third-party provider-specific status
return_code	String	Optional: ACH return code in the event of a returned transaction
return_description	String	Optional: ACH return code description
old_graph / old_route	String	Optional: Transaction route that it was cascaded from, One of: `ach_issue`, `ach_redeem`, `ledger_to_ledger`, `card_cko`, `ach_to_ach_with_operatingaccount`, `same_day_ach_pull`, `same_day_ach_push`, `rtp_pull`, `rtp_push`, `fednow_push`
new_route	String	Optional: Transaction route that it was cascaded to, One of: `ach_issue`, `ach_redeem`, `ledger_to_ledger`, `card_cko`, `ach_to_ach_with_operatingaccount`, `same_day_ach_pull`, `same_day_ach_push`, `rtp_pull`, `rtp_push`, `fednow_push`
externally_originated	boolean	Optional: identifies an externally originated transaction.
destination_id	string	Payment instrument UUID for the destination of the 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": 'a_user_handle',
    "processing_type": "STANDARD_ACH",
    "provider_status": "",
    "return_code": "",
    "old_route": "",
    "old_graph": "",
    "new_route": "",
    "externally_originated": false,
    "destination_id": "<uuid of destination payment instrument>"
  }
}

DEPRECATED - Transaction Created

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, 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 the account_link_status is updated to one of the following values when attempting to link an external bank account:

success
expired
failed

Key	Type	Description
account	String	UUID for Bank Account Linking
outcome	String	Bank Account Linking status. Can be one of: `success`, `expired`, `failed`
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": 'success',
    "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 user's 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": "account_nickname"
  }
}

Webhook Event Reference

Events and Webhook Payloads

Webhook Payload Object Common Properties

Advanced KYC kyc_status

Advanced KYC kyc_action

Classic KYC Status Update Event

📘
KYC outcomes in "failed" or "review" or "documents_required"

🚧
Review Statuses for /document uploads

Transaction Status Update

DEPRECATED - Transaction Created

Bank Account Linking

Bank Account Unfrozen/Frozen

Events and Webhook Payloads

Webhook Payload Object Common Properties

Advanced KYC kyc_status

Advanced KYC kyc_action

Classic KYC Status Update Event

📘KYC outcomes in "failed" or "review" or "documents_required"

🚧Review Statuses for /document uploads

Transaction Status Update

DEPRECATED - Transaction Created

Bank Account Linking

Bank Account Unfrozen/Frozen

📘
KYC outcomes in "failed" or "review" or "documents_required"

🚧
Review Statuses for /document uploads