Guides

Webhooks

Suggest Edits

A webhook is an HTTP request that keeps your system informed about changes in the Sikoia Platform in real-time. They facilitate instant communication between your system and Sikoia by triggering immediate notifications when specific events occur in the Sikoia Platform. This empowers your applications to respond promptly to relevant updates.

Supported Webhook Events

Below is a description of the various events you can configure a webhook to listen for. This will expand over time so please don’t assume it is exhaustive during development. For ease of readability events belong to one or more of four "groups":

  • Document Lifecycle
  • Banking
  • Identity Verification
  • Insights

Within each group events are arranged in a hierarchy whereby each event may have zero or more children that are more precise versions of their parent. For example, a PayslipProcessing.Completed event is a child of the more generic DocumentProcessing.Completed. If you wanted to be notified only when a Payslip was processed you would subscribe to the child, but if you wanted to be notified of any document that was processed in the Sikoia platform then you would subscribe to the parent.

Events that have no parent are referred to as "coarse" in our documentation. Events that have one or more parents are called "granular".

If you have subscribed to a coarse event and all of its granular children you should expect to receive as many webhook request as events you have subscribed to. For example, subscribing to both DocumentProcessing.Completed and PayslipProcessing.Completed will result in two webhooks being sent each time a payslip is processed.

🚧

An event can exist under multiple groups

For example BankStatementProcessing.Completed is categorised as both a Banking event and a Document event. If you subscribe to both DocumentProcessing.Completed and BankingProcessing.Completed you will receive two distinct webhooks each time a bank statement is processed.

You can find the latest list of supported event types by making a GET request for event types here and you can see an example below.

[
  {
    "event_group_name": "Document Lifecycle",
    "event_types": [
      {
        "event_name": "DocumentProcessing.Completed",
        "event_types": [
          {
            "event_name": "BankStatementProcessing.Completed",
            "event_types": []
          },
          {
            "event_name": "PayslipProcessing.Completed",
            "event_types": []
          }
        ]
      }
    ]
  },
  {
    "event_group_name": "Banking",
    "event_types": [
      {
        "event_name": "BankingProcessing.Completed",
        "event_types": [
          {
            "event_name": "OpenBankingProcessing.Completed",
            "event_types": []
          },
          {
            "event_name": "BankStatementProcessing.Completed",
            "event_types": []
          }
        ]
      }
    ]
  },
  {
    "event_group_name": "Identity Verification",
    "event_types": [
      {
        "event_name": "IdentityVerification.Completed",
        "event_types": []
      },
      {
        "event_name": "IdentityVerification.Expired",
        "event_types": []
      }
    ]
  },
  {
    "event_group_name": "Insights",
    "event_types": [
      {
        "event_name": "IncomeEmployerInsights.Completed",
        "event_types": []
      },
      {
        "event_name": "AffordabilityInsights.Completed",
        "event_types": []
      }
    ]
  }
]

Event Type Summary

Each event type shown in the JSON above is further explained below.

EventDescription
BankStatementProcessing.CompletedTriggered when a bank statement has been processed. This will be raised for bank statements that were successfully or unsuccessfully processed and you can use the status field in the response to be informed which it is.
AffordabilityInsights.CompletedTriggered when the status of an affordability insights request is updated to complete.
IdentityVerification.CompletedTriggered when an identity verification request is completed. This will be raised for identity verification attempts that were successful and unsuccessful.
IdentityVerification.ExpiredTriggered when an identity verification request expires - i.e. a user received a request to do the identity check but never completed it before the link expired.
OpenBankingProcessing.CompletedTriggered when an open banking connection request is completed by the end user and a new account is available in the system.
PayslipProcessing.CompletedTriggered when we have attempted to extract the data from a new payslip file that has been uploaded to our system. This webhook will contain both successful and unsuccessful results.
DocumentProcessing.CompletedTriggered whenever a document is processed. This currently only applies to bank statements and payslips. It may contain a successful or unsuccessful processing result and will always include the document type so you know the original source of the event.
BankingProcessing.CompletedTriggered whenever a banking response has been processed. This may be from a bank statement file being uploaded to our platform, or from an open banking connection being completed. It will contain a status field to inform you whether the operation succeeded or failed.
IncomeEmployerInsights.CompletedTriggered after a request to our API for income and employer verification has completed. This may take some time to complete but the response will include the status (success or failure) as well as the endpoint to query the full verification result.

Setting Up a Webhook

Configure Callback URL

To receive webhooks, setup a dedicated endpoint in your system which will act as the webhook_callback_url for receiving responses from Sikoia. Sikoia will send POST requests with a JSON payload to this endpoint.

curl -X POST 'https://yourdomain.com/webhook' \
-H 'Content-Type: application/json' \
-d '{"property": "value" }'

🚧

We currently only support public callback endpoints

Currently any value you provide for the webhook_callback_url must be publicly available to our system- i.e. it must not respond with an auth challenge when the webhook sends a POST.

Create a Webhook

Create a webhook using the create webhook endpoint and providing the following information:

  • webhook_name: A string with a maximum length of 50 characters.
  • webhook_callback_url: A valid HTTPS URL.
  • event_types: A list of events, selecting from the list above. At least one value must be provided.

Optionally, you can provide an external reference (such as an ID linking to an event in your internal systems) using the external_ref field.

You can modify any of the aforementioned fields using the update webhook endpoint after the webhook has been created.

Request Signing

You can enable request signing for all webhook requests by creating a secret key using the create webhook secret endpoint. This shared secret will be used to generate a SHA256 hash of every webhook's body content for each POST we make to the configured callback_url.

💡

The X-HMAC-SHA256-Signature header will be Base64 encoded

If you hash the request body yourself using the shared key and compare it against the unencoded header value it should be an exact match. Anything else should be disregarded as tampered with.

We only support a single global webhook secret, but you are free to rotate this value whenever you wish using the patch webhook secret endpoint. Every webhook sent after the date_updated UTC timestamp will use this new secret for signatures and you will not be able to use this value to verify signatures already sent on older requests. If you need to verify historic signatures you will need to maintain a list of previous secrets used (and the time period for them) yourself.

💡

Webhooks will be sent regardless of a secret existing

If no secret exists a webhook will still be sent, just without the X-HMAC-SHA256-Signature header. This is true for scenarios where you have never created a webhook secret and scenarios where a secret is deleted. We strongly recommend that you verify all requests but it is not mandatory.

Verifying a Signature

The exact code for doing this will vary depending on the language you choose, but at a high level you need to:

  • Check for the existence of the X-HMAC-SHA256-Signature header.
  • If it exists, decode the value from Base64.
  • Hash the request body you received using the SHA256 algorithm making sure you use the secret as the key.
  • Compare the two hash values - if they match exactly you can trust it has not been tampered with. Otherwise disregard the webhook as malicious.

🚧

Both the secret and the request body must be treated as UTF-8 encoded strings

You must also ensure you only use exactly the body content of the POST request as the value to be hashed. Any deviation from this will produce a non-matching hash.

The following code snippets show examples of how you can use the shared secret key to compare the hash we send in the header against your own hash of the POST request body. If there is a specific language you need an example for, or you are encountering issues comparing the hash please do get in touch.

var secretKey = "994caa23-dbf4-405c-8a04-5326ee31236c";
var hamcHeaderSignature = "rqcuIA6CC9OGpWZIIVyMNBr2uH2Ok2T1N/ba41AwBCk=";
var requestBody = "{\"webhook_id\":\"500cce08-0ace-4620-937b-d75275554027\",\"webhook_name\":\"Demo Hook\",\"datetime_sent\":\"2024-06-25T09:57:12.517Z\",\"external_ref\":\"Current Reference\",\"event_type\":\"DocumentProcessing.Completed\",\"data\":{\"status\":\"cb8f457f-a930-4cc8-8b24-4b9deb53b477\",\"message\":\"757da020-2243-4339-a219-4c9522562981\",\"document_type\":\"doc01\",\"document\":{\"document_id\":\"716a70c1-a8ea-43cd-9a02-cceb8926365e\",\"document_endpoint\":\"https://api.sikoia.com/v2/documents/716a70c1-a8ea-43cd-9a02-cceb8926365e\",\"file_name\":\"f106d60b-b419-41d1-853d-06995f78e7fb\"}}}";

var isValid = IsSignatureValid(secretKey, hamcHeaderSignature, requestBody);

// Handle the webhook if valid, otherwise reject

static bool IsSignatureValid(string secretKey, string expectedHash, string requestBodyJson)
{
    var secretValue = Encoding.UTF8.GetBytes(secretKey);
    var encodedRequestBody = Encoding.UTF8.GetBytes(requestBodyJson);
    var actualHash = HMACSHA256.HashData(secretValue, encodedRequestBody);

    return StructuralComparisons.StructuralEqualityComparer.Equals(expectedHash, actualHash);
}

Webhook Responses

Webhook events are sent as POST requests, with a JSON payload having the following base structure:

{
    "webhook_id": "<guid>",
    "webhook_name": "<string>",
    "datetime_sent": "<datetime>",
    "external_ref": "<string>",
    "event_type": "<string>",
    "data": { }
}

The object value of data will change depending on the specific event type.

Example: BankStatementProcessing.Completed event

When we've processed a bank statement we will send this event for both successful and unsuccessful results. Both responses have the same structure, but a failure will have a null value for the bank_connection_id and an empty array for the connected_accounts. You will always receive a reason in the message property to explain any non Complete status. A successful Complete response will provide a list of all accounts that were connected which will allow you to request account information including balances and transactions with the pre-formatted endpoint URLs.

{
    "webhook_id": "153c6cf4-6dc3-4846-a5fa-ac308065b2d1",
    "webhook_name": "Webhook Name",
    "datetime_sent": "2024-02-15T10:50:32.7754111Z",
    "external_ref": null,
    "event_type": "BankStatementProcessing.Completed",
    "data": {
        "bank_connection_id": "59c4f272-1c4a-4275-8dce-ae1c51b9259e",
        "status": "Complete",
        "message": null,
        "entity_type": "Case",
        "entity_id": "7a778782-e585-4f15-a25f-1aaed7d30214",
        "document": {
            "document_id": "65bc31cb-f23d-4f6d-920e-e5dd85eefa69",
            "document_endpoint": "https://api.sikoia.com/v2/documents/65bc31cb-f23d-4f6d-920e-e5dd85eefa69",
            "file_name": "Filename.pdf"
        },
        "connected_accounts": [
            {
                "account_connection_id": "35661239-5900-4d86-9d95-2b6342cd780d",
                "bank_account_endpoint": "https://api.sikoia.com/v2/bankaccounts/35661239-5900-4d86-9d95-2b6342cd780d",
                "bank_account_balances_endpoint": "https://api.sikoia.com/v2/bankaccounts/35661239-5900-4d86-9d95-2b6342cd780d/balances",
                "bank_account_transactions_endpoint": "https://api.sikoia.com/v2/bankaccounts/35661239-5900-4d86-9d95-2b6342cd780d/transactions"
            },
            {
                "account_connection_id": "d9736d61-3fc8-4470-b768-623fa7ebdbdd",
                "bank_account_endpoint": "https://api.sikoia.com/v2/bankaccounts/d9736d61-3fc8-4470-b768-623fa7ebdbdd",
                "bank_account_balances_endpoint": "https://api.sikoia.com/v2/bankaccounts/d9736d61-3fc8-4470-b768-623fa7ebdbdd/balances",
                "bank_account_transactions_endpoint": "https://api.sikoia.com/v2/bankaccounts/d9736d61-3fc8-4470-b768-623fa7ebdbdd/transactions"
            }
        ]
    }
}

{
    "webhook_id": "153c6cf4-6dc3-4846-a5fa-ac308065b2d1",
    "webhook_name": "Webhook Name",
    "datetime_sent": "2024-02-15T10:50:32.7754111Z",
    "external_ref": null,
    "event_type": "BankStatementProcessing.Completed",
    "data": {
        "bank_connection_id": null,
        "status": "Failed",
        "message": "Could not process bank statement provided.",
        "entity_type": "Case",
        "entity_id": "7a778782-e585-4f15-a25f-1aaed7d30214",
        "document": {
            "document_id": "65bc31cb-f23d-4f6d-920e-e5dd85eefa69",
            "document_endpoint": "https://api.sikoia.com/v2/documents/65bc31cb-f23d-4f6d-920e-e5dd85eefa69",
            "file_name": "Filename.pdf"
        },
        "connected_accounts": []
    }
}

Example: AffordabilityInsights.Completed event

When affordability insights have completed and an event is raised you will receive the request_id associated with the insight as well as the pre-formatted URLs necessary to request the full insight data - including transactions.

{
    "webhook_id": "f7d11ee7-d766-4277-ad76-3106ae31ef35",
    "webhook_name": "Insights Example",
    "sent_at_utc": "2024-02-06T16:10:23.3375831Z",
    "external_ref": "IntRef002",
    "event_type": "AffordabilityInsights.Completed",
    "data": {
        "request_id": "c6e49c56-5232-41fc-804b-0b3cda972e10",
        "affordability_insight_endpoint": "https://api.sikoia.com/v2/affordability-insights/c6e49c56-5232-41fc-804b-0b3cda972e10",
        "affordability_insight_transactions_endpoint": "https://api.sikoia.com/v2/affordability-insights/c6e49c56-5232-41fc-804b-0b3cda972e10/transactions"
    }
}

Example: IdentityVerification.Completed event

For both successful and unsuccessful identity verification attempts you will receive the same payload structure. The difference will be in the verification_status value which can be one of three values: Approved, Declined, and ResubmissionRequested. You can retrieve further identity specific data by making a GET request to the endpoints inside identity_request.

{
    "webhook_id": "5a78b6fd-fc87-4ab7-a0cc-b3bde95e16d3",
    "webhook_name": "Identity Completed Webhook",
    "datetime_sent": "2024-02-21T21:40:37.212Z",
    "external_ref": "IntRef001",
    "event_type": "IdentityVerification.Completed",
    "data": {
        "identity_request": {
            "request_id": "db88598f-66dc-4e42-a466-7574eb6e9c5b",
            "identity_request_endpoint": "https://api.sikoia.com/v2/persons/a2369aea-da2c-469b-8b0f-dd27b864b2c7/identity-verifications",
            "identity_result_endpoint": "https://api.sikoia.com/v2/identity/db88598f-66dc-4e42-a466-7574eb6e9c5b"
        },
        "person": {
            "first_name": "John",
            "last_name": "Smith",
            "name": "John Smith",
            "person_id": "a2369aea-da2c-469b-8b0f-dd27b864b2c7"
        },
        "status": "Completed",
        "date_completed": "2024-02-21T17:37:10.648Z",
        "verification_status": "Approved"
    }
}

{
    "webhook_id": "5a78b6fd-fc87-4ab7-a0cc-b3bde95e16d3",
    "webhook_name": "Identity Completed Webhook",
    "datetime_sent": "2024-02-21T21:40:37.212Z",
    "external_ref": "IntRef001",
    "event_type": "IdentityVerification.Completed",
    "data": {
        "identity_request": {
            "request_id": "db88598f-66dc-4e42-a466-7574eb6e9c5b",
            "identity_request_endpoint": "https://api.sikoia.com/v2/persons/a2369aea-da2c-469b-8b0f-dd27b864b2c7/identity-verifications",
            "identity_result_endpoint": "https://api.sikoia.com/v2/identity/db88598f-66dc-4e42-a466-7574eb6e9c5b"
        },
        "person": {
            "first_name": "John",
            "last_name": "Smith",
            "name": "John Smith",
            "person_id": "a2369aea-da2c-469b-8b0f-dd27b864b2c7"
        },
        "status": "Completed",
        "date_completed": "2024-02-21T17:37:10.648Z",
        "verification_status": "Declined"
    }
}

Example: IdentityVerification.Expired event

This will only be sent if a user was sent a link to complete the identity check but never actually submitted it before the expiry period. The structure is very similar to the IdentityVerification.Completed event, except that it does not have a date_completed value. 

{
    "webhook_id": "6337c40f-c266-419c-9252-7018d321bddd",
    "webhook_name": "Identity Expired Webhook",
    "datetime_sent": "2024-02-21T21:44:40.344Z",
    "external_ref": "IntRef001",
    "event_type": "IdentityVerification.Expired",
    "data": {
        "identity_request": {
            "request_id": "ae9b44dd-e1c1-4d68-bbae-1f204ac9e328",
            "identity_request_endpoint": "https://api.sikoia.com/v2/persons/dfc9419e-3e7c-4bab-92ec-dc813e2b960f/identity-verifications",
            "identity_result_endpoint": "https://api.sikoia.com/v2/identity/ae9b44dd-e1c1-4d68-bbae-1f204ac9e328"
        },
        "person": {
            "first_name": "John",
            "last_name": "Smith",
            "name": "John",
            "person_id": "dfc9419e-3e7c-4bab-92ec-dc813e2b960f"
        },
        "status": "Expired",
        "verification_status": "NotCompleted"
    }
}

Example: OpenBankingProcessing.Completed event

When an open banking connection request is completed by the end user we will send this event containing the details of each account that was connected (there may be multiple e.g. current account, savings etc). We will return the overall connection status, as well as pre-formatted URLs to call our various banking endpoints for retrieving account, balance and transaction data. If the connection attempt failed we will return a status indicating why and an empty array of accounts.

{
    "webhook_id": "38f9b104-02e9-4079-bb49-0af2788c84f7",
    "webhook_name": "OB Completed Hook",
    "datetime_sent": "2024-02-26T22:04:12.533Z",
    "external_ref": "IntRef001",
    "event_type": "OpenBankingProcessing.Completed",
    "data": {
        "bank_connection_id": "2581f009-ac98-4e0a-bc90-6a6860fb9ee6",
        "status": "Connected",
        "entity_type": "Case",
        "entity_id": "8cd27914-08ac-4669-981d-29f2c3542e91",
        "connected_accounts": [
            {
                "account_connection_id": "35661239-5900-4d86-9d95-2b6342cd780d",
                "bank_account_endpoint": "https://api-dev.sikoia.com/v2/bankaccounts/35661239-5900-4d86-9d95-2b6342cd780d",
                "bank_account_balances_endpoint": "https://api.sikoia.com/v2/bankaccounts/35661239-5900-4d86-9d95-2b6342cd780d/balances",
                "bank_account_transactions_endpoint": "https://api.sikoia.com/v2/bankaccounts/35661239-5900-4d86-9d95-2b6342cd780d/transactions"
            },
            {
                "account_connection_id": "d9736d61-3fc8-4470-b768-623fa7ebdbdd",
                "bank_account_endpoint": "https://api.sikoia.com/v2/bankaccounts/d9736d61-3fc8-4470-b768-623fa7ebdbdd",
                "bank_account_balances_endpoint": "https://api.sikoia.com/v2/bankaccounts/d9736d61-3fc8-4470-b768-623fa7ebdbdd/balances",
                "bank_account_transactions_endpoint": "https://api.sikoia.com/v2/bankaccounts/d9736d61-3fc8-4470-b768-623fa7ebdbdd/transactions"
            }
        ]
    }
}

{
    "webhook_id": "38f9b104-02e9-4079-bb49-0af2788c84f7",
    "webhook_name": "OB Completed Hook",
    "datetime_sent": "2024-02-26T22:04:12.533Z",
    "external_ref": "IntRef001",
    "event_type": "OpenBankingProcessing.Completed",
    "data": {
        "bank_connection_id": "2581f009-ac98-4e0a-bc90-6a6860fb9ee6",
        "status": "Rejected",
        "entity_type": "Case",
        "entity_id": "8cd27914-08ac-4669-981d-29f2c3542e91",
        "connected_accounts": []
    }
}

Example: PayslipProcessing.Completed event

When a new file is uploaded and categorised as a Payslip (either because the user explicitly marked it as one, or the system recognised it as such) we will try and extract the expected data from the file - e.g. the amount paid, the time period it was for, any pension contributions etc. Once extracted this data can then be used in our wider income and employer verification workflows.

If the data extraction succeeds you will receive a webhook with a "Success" status and a link to the file that we were able to process. If the extraction fails, you will still receive a link to the file, but the status will be "Failed". If there is a failure, then please ensure the file uploaded is a well formed payslip.

{
    "webhook_id": "a92ee317-6f9e-4f5d-9983-f9d200b57867",
    "webhook_name": "Payslip Webhook",
    "datetime_sent": "2024-03-14T14:51:49.402Z",
    "external_ref": null,
    "event_type": "PayslipProcessing.Completed",
    "data": {
        "status": "Complete",
        "message": null,
        "document": {
            "document_id": "42ea06dd-3a40-408b-a4ce-883465e46404",
            "document_endpoint": "https://api.sikoia.com/v2/documents/42ea06dd-3a40-408b-a4ce-883465e46404",
            "file_name": "25082022-demo-payslip.pdf"
        }
    }
}

{
    "webhook_id": "a92ee317-6f9e-4f5d-9983-f9d200b57867",
    "webhook_name": "Payslip Webhook",
    "datetime_sent": "2024-03-14T14:51:49.402Z",
    "external_ref": null,
    "event_type": "PayslipProcessing.Completed",
    "data": {
        "status": "Failed",
        "message": "Error message explaining the failure",
        "document": {
            "document_id": "42ea06dd-3a40-408b-a4ce-883465e46404",
            "document_endpoint": "https://api.sikoia.com/v2/documents/42ea06dd-3a40-408b-a4ce-883465e46404",
            "file_name": "25082022-demo-payslip.pdf"
        }
    }
}

Example: DocumentProcessing.Completed event

Whenever a document is processed in the Sikoia platform (currently only applies to Bank Statements and Payslips) we will send this event to any webhook subscribed to it. In the example below we're using a Payslip as the source of the event. Both success and failure payloads will contain a link back to the original file that was processed and you can use the status/message values to give context to any failure.

{
    "webhook_id": "45a3acfb-3afb-4999-abfe-78d629a57e16",
    "webhook_name": "Document Webhook",
    "datetime_sent": "2024-03-25T23:20:13.481Z",
    "external_ref": null,
    "event_type": "DocumentProcessing.Completed",
    "data": {
        "status": "Complete",
        "message": null,
        "document_type": "Payslip",
        "document": {
            "document_id": "41f04dbf-2071-48df-b3fa-6550f08b7cc2",
            "document_endpoint": "https://api.sikoia.com/v2/documents/41f04dbf-2071-48df-b3fa-6550f08b7cc2",
            "file_name": "Payslip.pdf"
        }
    }
}

{
    "webhook_id": "45a3acfb-3afb-4999-abfe-78d629a57e16",
    "webhook_name": "Document Webhook",
    "datetime_sent": "2024-03-25T23:20:13.481Z",
    "external_ref": null,
    "event_type": "DocumentProcessing.Completed",
    "data": {
        "status": "Failed",
        "message": "Error explaining the failure",
        "document_type": "Payslip",
        "document": {
            "document_id": "41f04dbf-2071-48df-b3fa-6550f08b7cc2",
            "document_endpoint": "https://api.sikoia.com/v2/documents/41f04dbf-2071-48df-b3fa-6550f08b7cc2",
            "file_name": "Payslip.pdf"
        }
    }
}

Example: BankingProcessing.Completed event

Whenever a banking workflow is completed in the Sikoia platform (either from a bank statement being uploaded or an open banking request completing) we will send this event to any webhook subscribed to it. We will send this event containing the details of each account that was connected (there may be multiple e.g. current account, savings etc). We will return the overall connection status, as well as pre-formatted URLs to call our various banking endpoints for retrieving account, balance and transaction data. If the processing failed we will return a status indicating why and an empty array of accounts.

{
    "webhook_id": "45a3acfb-3afb-4999-abfe-78d629a57e16",
    "webhook_name": "Banking Webhook",
    "datetime_sent": "2024-03-25T17:42:31.885Z",
    "external_ref": null,
    "event_type": "BankingProcessing.Completed",
    "data": {
        "bank_connection_id": "b705e1ec-48e1-4e76-aeb3-14cbe84b50f1",
        "status": "Complete",
        "entity_type": "case",
        "entity_id": "7af65a1c-a4e0-4e7b-ae7e-64a422bdb6d8",
        "connected_accounts": [
            {
                "account_connection_id": "baf411d6-d38a-4cf6-a395-a9bbae40789a",
                "bank_account_endpoint": "https://api.sikoia.com/v2/bankaccounts/baf411d6-d38a-4cf6-a395-a9bbae40789a",
                "bank_account_balances_endpoint": "https://api.sikoia.com/v2/bankaccounts/baf411d6-d38a-4cf6-a395-a9bbae40789a/balances",
                "bank_account_transactions_endpoint": "https://api.sikoia.com/v2/bankaccounts/baf411d6-d38a-4cf6-a395-a9bbae40789a/transactions"
            }
        ]
    }
}

{
    "webhook_id": "45a3acfb-3afb-4999-abfe-78d629a57e16",
    "webhook_name": "Banking Webhook",
    "datetime_sent": "2024-03-25T17:42:31.885Z",
    "external_ref": null,
    "event_type": "BankingProcessing.Completed",
    "data": {
        "bank_connection_id": "b705e1ec-48e1-4e76-aeb3-14cbe84b50f1",
        "status": "Rejected",
        "entity_type": "case",
        "entity_id": "7af65a1c-a4e0-4e7b-ae7e-64a422bdb6d8",
        "connected_accounts": []
    }
}

Example: IncomeEmployerInsights.Completed event

Triggered after a request to our API for income and employer verification has completed. This may take some time to complete but the response will include the status (success or failure) as well as the endpoint to query the full verification result. Even if the request fails you will still get a link back to the verification endpoint where you can find more information about the failure.

{
    "webhook_id": "45a3acfb-3afb-4999-abfe-78d629a57e16",
    "webhook_name": "Income Webhook",
    "datetime_sent": "2024-03-26T10:20:25.362Z",
    "external_ref": null,
    "event_type": "IncomeEmployerInsights.Completed",
    "data": {
        "status": "Complete",
        "message": "Income Employer Request Completed",
        "entity_type": "Case",
        "entity_id": "880c5618-cacb-4f19-a795-85bf7ba57a08",
        "datetime_requested": "2024-03-26T10:20:22.583Z",
        "datetime_completed": "2024-03-26T10:20:25.063Z",
        "income_and_employer_request": {
            "request_id": "81487e28-9bcb-429e-bc10-c1c64eaa03ae",
            "verification_endpoint": "https://api.sikoia.com/v2/income-employer/81487e28-9bcb-429e-bc10-c1c64eaa03ae"
        }
    }
}

{
    "webhook_id": "45a3acfb-3afb-4999-abfe-78d629a57e16",
    "webhook_name": "Income Webhook",
    "datetime_sent": "2024-03-26T10:20:25.362Z",
    "external_ref": null,
    "event_type": "IncomeEmployerInsights.Completed",
    "data": {
        "status": "Failed",
        "message": "Message explaining the failure",
        "entity_type": "Case",
        "entity_id": "880c5618-cacb-4f19-a795-85bf7ba57a08",
        "datetime_requested": "2024-03-26T10:20:22.583Z",
        "datetime_completed": "2024-03-26T10:20:25.063Z",
        "income_and_employer_request": {
            "request_id": "81487e28-9bcb-429e-bc10-c1c64eaa03ae",
            "verification_endpoint": "https://api.sikoia.com/v2/income-employer/81487e28-9bcb-429e-bc10-c1c64eaa03ae"
        }
    }
}

Batching and Correlation

We send a X-Batch-Correlation-Id header in all webhooks to group together related requests. If you have multiple webhooks setup for the same event type and this event is triggered from within the Sikoia platform you will receive one request per webhook configured - whereby each callback url you defined receives the same payload. As such you can use this header to correlate these requests if needed.

Replies and Retries

We accept any 2XX response to a webhook POST. Other responses are marked as failures. No retries are currently attempted for failed webhook requests.

Endpoints

Start exploring Sikoia's webhook endpoints here.

Updated 2 months ago