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

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"

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 (wires and 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

sila_amount

Integer

Amount of SILA tokens used in the transaction. The sila_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_ACH, INSTANT_SETTLEMENT

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",
    "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.

Key

Type

Description

transaction

String

UUID for transaction

transaction_type

String

Type of transaction: issue

sila_amount

Integer

Amount of SILA tokens used in the transaction. The sila_amount is equivalent to a 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

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.

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.

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

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.

Key

Type

Description

sms_opt_in_status

String

status based on entities response. True if yes, false if not.

phone

String

UUID of Phone

entity

String

Registered user handle

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

Did this page help you?