Skip to main content

Overview

Webhooks instantly inform your application about significant events, such as payroll submissions or updates, without the need for polling.

Use Cases:

  • Alerting when users submit or create payroll data. This use case can be handled by subscribing for event of type user-payroll-submitted
  • Notifying upon successful account linkages. Not yet supported as event type.
  • Triggering actions after data updates. Not yet supported as event type.
Webhooks are system-wide meaning subscriptions are not limited to specific users or accounts. For example, if any user updates their payroll with the user-payroll-submitted subscription enabled, a webbook will be delivered with the respective user information enclosed.

Quick Reference:

  • Webhooks List: Detailed descriptions of all events you can subscribe to.
  • Setup Guide: Instructions for subscribing and managing webhooks.

Supported Event:

  • user-payroll-submitted - notifies when any user creates an entry with new payroll data. Includes the payroll data entry as json if include_payload is set in the configuration.
  • user-bank-statement-submitted - notifies when any user uploads bank statements that are successfully extracted. Includes bank statement submissions as json if include_payload is set in the configuration.

Setting Up Webhooks

Create a webhook by sending a POST request. Specify which events to monitor and where to send notifications.
curl --request POST \
  --url https://api.sandbox.goteal.co/webhooks \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '{
    "events": ["user-payroll-submitted", "user-payroll-created"],
    "name": "user-payroll-submitted",
    "signing_secret": "very-secret",
    "encryption_key": "St/73LZ1xHkwX5TanL7V+YAVczn4acozPf3cFySKQXI=",
    "url": "https://webhooks.site"
  }'
  • events: Choose events like user-payroll-submitted or user-bank-statement-submitted for targeted notifications.
  • name: Label your webhook for easier management.
  • url: Your endpoint to receive webhook payloads.
  • signing_secret: (Optional) A secret for secure webhook verification.
  • encryption_key: (Optional) A Base64-encoded 32-byte key used to encrypt webhook payloads.

Verifying Webhooks

If the optional signing_secret was provided in the webhook subscription, it can be used to validate incoming webhook signatures, ensuring data integrity and authenticity. When encryption is enabled, the message is first encrypted and then signed. Therefore, the signature should be verified against the encrypted message, not the decrypted content. To verify if a received webhook event is authentic:
  • Encode the webook payload with the signing_secret using HMAC-SHA512. You can then check that the result of this encoding matches the contents in the X-Teal-Signature header. If it matches then the webhook received is genuine. Example verification:
If your signing_secret was mysecret and you received the following webhook payload:
{
    "event": "user-payroll-submitted",
    "user_id": "4708334c-70b3-437d-8e46-91ff5c9a8d7d",
    "timestamp": "2024-04-04T12:00:00.00Z"
}
The signature to check against would be:
"X-Teal-Signature" : "a30540779107a19069257432b775b74b16b32214616638fae2e6027a41a3f2dfb08f44daf3862c335d08fb83501fc769f73d49a1cb137f96f31c6a7db412c197"
Example of verifying signature:
const crypto = require('crypto');

// The signature as "X-Teal-Signature" header
const receivedTealSignature = '...'; 
const client_secret = 'my little secret';
const requestBody = '...'; // Your request body here

// Make sure to use the raw requestBody when validating the signature.
var signature = crypto
  .createHmac('sha512', client_secret)
  .update(requestBody)
  .digest('hex');

if (receivedTealSignature === signature) {
    console.log('Signature is valid');
} else {
    console.log('Signature is invalid');
}
import hmac
import hashlib

receivedTealSignature = '...'  # The signature as "X-Teal-Signature" header
client_secret = 'my little secret'
requestBody = '...'  # Your request body here

# Make sure to use the raw requestBody when validating the signature.
signature = hmac.new(
  client_secret.encode(),
  msg=requestBody.encode(),
  digestmod=hashlib.sha512
).hexdigest()

if receivedTealSignature == signature:
    print('Signature is valid')
else:
    print('Signature is invalid')
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;

public class Main {
    public static void main(String[] args) throws Exception {

        // The signature as "X-Teal-Signature" header
        String receivedTealSignature = "...";
        String client_secret = "my little secret";
        String requestBody = "...";  // Your request body here

        // Make sure to use the raw requestBody when validating the signature.
        Mac sha512_HMAC = Mac.getInstance("HmacSHA512");
        SecretKeySpec secret_key = new SecretKeySpec(
          client_secret.getBytes(StandardCharsets.UTF_8),
          "HmacSHA512"
        );
        sha512_HMAC.init(secret_key);

        byte[] hash = sha512_HMAC
        .doFinal(requestBody.getBytes(StandardCharsets.UTF_8));
        StringBuilder sb = new StringBuilder(hash.length * 2);
        for(byte b : hash) {
            sb.append(String.format("%02x", b));
        }
        String signature = sb.toString();

        if (receivedTealSignature.equals(signature)) {
            System.out.println("Signature is valid");
        } else {
            System.out.println("Signature is invalid");
        }
    }
}
import javax.crypto.Mac
import javax.crypto.spec.SecretKeySpec
import java.nio.charset.StandardCharsets
import java.security.InvalidKeyException
import java.security.NoSuchAlgorithmException

 // The signature as "X-Teal-Signature" header
val receivedTealSignature = "..." 
val client_secret = "my little secret"
val requestBody = "..."  // Your request body here

// Make sure to use the raw requestBody when validating the signature.
val sha512_HMAC = Mac.getInstance("HmacSHA512")
val secret_key = SecretKeySpec(
  client_secret.toByteArray(StandardCharsets.UTF_8),
  "HmacSHA512"
)
sha512_HMAC.init(secret_key)

val hash = sha512_HMAC
    .doFinal(requestBody.toByteArray(StandardCharsets.UTF_8))
val signature = hash.joinToString("") { "%02x".format(it) }

if (receivedTealSignature == signature) {
    println("Signature is valid")
} else {
    println("Signature is invalid")
}

Generating Encryption Keys

If you want to use encrypted webhooks, you’ll need to provide a 32-byte encryption key encoded in Base64 when creating your webhook. Here’s how to generate a secure random key in different languages:
const crypto = require('crypto');

// Generate a random 32-byte key
const encryptionKey = crypto.randomBytes(32);

// Encode the key as Base64 for use with the API
const encryptionKeyBase64 = encryptionKey.toString('base64');
console.log('Encryption Key:', encryptionKeyBase64);
// Example output: St/73LZ1xHkwX5TanL7V+YAVczn4acozPf3cFySKQXI=
import os
import base64

# Generate a random 32-byte key
encryption_key = os.urandom(32)

# Encode the key as Base64 for use with the API
encryption_key_base64 = base64.b64encode(encryption_key).decode('utf-8')
print(f"Encryption Key: {encryption_key_base64}")
# Example output: St/73LZ1xHkwX5TanL7V+YAVczn4acozPf3cFySKQXI=
import java.security.SecureRandom;
import java.util.Base64;

public class GenerateEncryptionKey {
    public static void main(String[] args) {
        // Generate a random 32-byte key
        SecureRandom secureRandom = new SecureRandom();
        byte[] key = new byte[32];
        secureRandom.nextBytes(key);
        
        // Encode the key as Base64 for use with the API
        String encryptionKeyBase64 = Base64.getEncoder().encodeToString(key);
        System.out.println("Encryption Key: " + encryptionKeyBase64);
        // Example output: St/73LZ1xHkwX5TanL7V+YAVczn4acozPf3cFySKQXI=
    }
}
import java.security.SecureRandom
import java.util.Base64

// Generate a random 32-byte key
val secureRandom = SecureRandom()
val key = ByteArray(32)
secureRandom.nextBytes(key)

// Encode the key as Base64 for use with the API
val encryptionKeyBase64 = Base64.getEncoder().encodeToString(key)
println("Encryption Key: $encryptionKeyBase64")
// Example output: St/73LZ1xHkwX5TanL7V+YAVczn4acozPf3cFySKQXI=

Decrypting Webhook Payloads

When you provide an encryption_key, the webhook payload will be encrypted using AES/GCM/NoPadding. To decrypt:
  1. The encrypted payload is sent in the request body
  2. The initialization vector is provided in the X-Teal-Encryption-IV header (Base64 encoded)
Here’s how to decrypt the payload in different languages:
const crypto = require('crypto');

function decrypt(
    encryptedBase64,
    ivBase64,
    encryptionKeyBase64
) {
    const encryptionKey = Buffer.from(encryptionKeyBase64, 'base64');
    const iv = Buffer.from(ivBase64, 'base64');
    const encryptedBuffer = Buffer.from(encryptedBase64, 'base64');

    // Extract the auth tag (last 16 bytes) and ciphertext
    const authTag = encryptedBuffer.subarray(encryptedBuffer.length - 16);
    const ciphertext = encryptedBuffer.subarray(0, encryptedBuffer.length - 16);

    const decipher = crypto.createDecipheriv('aes-256-gcm', encryptionKey, iv);
    decipher.setAuthTag(authTag);
    let decrypted = decipher.update(ciphertext);
    try {
        const final = decipher.final();
        if (final.length > 0) {
            decrypted = Buffer.concat([decrypted, final]);
        }

        const payload = JSON.parse(decrypted.toString('utf8'));
        console.log('Decrypted payload:', payload);
    } catch (error) {
        console.error('Decryption failed:', error);
    }
}

decrypt(
    webhookRequest.body,
    webhookRequest.headers['x-teal-encryption-iv'],
    yourSecretStorage.base64EncryptionKey
)
import base64
import json
from Crypto.Cipher import AES

def decrypt(
    encrypted_base64: str,
    iv_base64: str,
    encryption_key_base64: str
) -> dict:
    encryption_key = base64.b64decode(encryption_key_base64)
    print(f"Key length: {len(encryption_key)} bytes")
    iv = base64.b64decode(iv_base64)
    print(f"IV length: {len(iv)} bytes")

    encrypted_data = base64.b64decode(encrypted_base64)
    print(f"Encrypted data length: {len(encrypted_data)} bytes")

    auth_tag = encrypted_data[-16:]
    ciphertext = encrypted_data[:-16]
    print(f"Auth tag length: {len(auth_tag)} bytes")
    print(f"Ciphertext length: {len(ciphertext)} bytes")

    cipher = AES.new(encryption_key, AES.MODE_GCM, nonce=iv)

    decrypted_data = cipher.decrypt_and_verify(ciphertext, auth_tag)

    payload = json.loads(decrypted_data.decode('utf-8'))
    print("Decryption successful!")
    print(f"Decrypted payload: {payload}")
    return payload

if __name__ == "__main__":
    decrypt(
        webhookRequest.body,
        webhookRequest.headers["x-teal-encryption-iv"],
        secretStorage.base64Secret
    )
import javax.crypto.Cipher;
import javax.crypto.spec.GCMParameterSpec;
import javax.crypto.spec.SecretKeySpec;
import java.util.Base64;

public class DecryptMessage {

    public static String decryptWebhookPayload(
        String encryptedData,
        String encryptionKey,
        String ivBase64
    ) throws Exception {
        byte[] key = Base64.getDecoder().decode(encryptionKey);
        byte[] iv = Base64.getDecoder().decode(ivBase64);
        byte[] encryptedBytes = Base64.getDecoder().decode(encryptedData);

        SecretKeySpec secretKey = new SecretKeySpec(key, "AES");
        Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding");
        GCMParameterSpec spec = new GCMParameterSpec(128, iv);

        cipher.init(Cipher.DECRYPT_MODE, secretKey, spec);
        byte[] decryptedBytes = cipher.doFinal(encryptedBytes);

        return new String(decryptedBytes, "UTF-8");
    }

    public static void main(String[] args) {
        try {
            String result = decryptWebhookPayload(
                "nBPqEB4T1g/88q1P2qm7oYH5MYbR/NpCVBCytMZsB7ux4xR+OYPS8Y/Ye8giQb6UplDitbKlFlHPoA6pzMu3CmD2cew4JvluyKiOQBE61OwETwJ++KkvwuB9WxegKnhncWqg6qwn9WkRGtmKpfrxiXrdvj7V4aKSOFkO8ByWYztQp58Ublm3yNPQyQmnzJOR+/4v8OMbVivcAkumRu8PO2EYr2uqfPvNMonXiNE5fnqJieZKFvRnDi+s6TNZpSsCzWPgfDGn+EqiDbjqWw+eWnUYd3BQ75OOJficovrzk1dYkONm5uYTnZYSdiwMzNm7",
                "7/PxZATSzWbQkS8ZjSt0f+bTMt9oQ6jkm0aYFe3NN24=",
                "vdBbe9Tk7aqo1pZi"
            );
            System.out.println("Decrypted payload: " + result);
        } catch (Exception e) {
            System.err.println("Decryption failed: " + e.getMessage());
            e.printStackTrace();
        }
    }
}
import java.util.Base64
import javax.crypto.Cipher
import javax.crypto.spec.GCMParameterSpec
import javax.crypto.spec.SecretKeySpec

fun decryptWebhookPayload(
    encryptedData: String,
    encryptionKey: String,
    ivBase64: String
): String {
    val key = Base64.getDecoder().decode(encryptionKey)
    val iv = Base64.getDecoder().decode(ivBase64)
    val encryptedBytes = Base64.getDecoder().decode(encryptedData)
    val secretKey = SecretKeySpec(key, "AES")
    val cipher = Cipher.getInstance("AES/GCM/NoPadding")
    val spec = GCMParameterSpec(128, iv)
    cipher.init(Cipher.DECRYPT_MODE, secretKey, spec)
    val decryptedBytes = cipher.doFinal(encryptedBytes)
    return String(decryptedBytes, Charsets.UTF_8)
}

fun main() {
    try {
        val result = decryptWebhookPayload(
            "nBPqEB4T1g/88q1P2qm7oYH5MYbR/NpCVBCytMZsB7ux4xR+OYPS8Y/Ye8giQb6UplDitbKlFlHPoA6pzMu3CmD2cew4JvluyKiOQBE61OwETwJ++KkvwuB9WxegKnhncWqg6qwn9WkRGtmKpfrxiXrdvj7V4aKSOFkO8ByWYztQp58Ublm3yNPQyQmnzJOR+/4v8OMbVivcAkumRu8PO2EYr2uqfPvNMonXiNE5fnqJieZKFvRnDi+s6TNZpSsCzWPgfDGn+EqiDbjqWw+eWnUYd3BQ75OOJficovrzk1dYkONm5uYTnZYSdiwMzNm7",
            "7/PxZATSzWbQkS8ZjSt0f+bTMt9oQ6jkm0aYFe3NN24=",
            "vdBbe9Tk7aqo1pZi"
        )
        println("Decrypted payload: $result")
    } catch (e: Exception) {
        println("Decryption failed: ${e.message}")
        e.printStackTrace()
    }
}

Webhook Management

Viewing subscriptions

List your current webhooks with a simple GET request to our webhook endpoint GET /webhooks.

Deleting subscriptions

Unsubscribe using the webhook ID in the request DELETE /webhooks/{webhook_id}

Best Practices

  • Secure Endpoints: Ensure your webhook URL is HTTPS-secured to safeguard transmitted data.
  • Manage Secrets: Keep your signing_secret and encryption_key confidential.
  • Use Encryption: Consider using the encryption feature when your team doesn’t control HTTPS termination and you want payloads to be decrypted only by applications possessing the encryption key. As an example, this could help prevent sensitive or GDPR-regulated information from being logged in systems not designed to handle such data (there might be more cases for your specific situation).
  • Alternative to Encryption: As an alternative to encryption, consider disabling the payload in webhooks by not setting include_payload in your webhook configuration.
  • Regular Review: Periodically check your webhook subscriptions and adjust as needed to match your application’s requirements.
Leverage our webhooks to make your application more dynamic and responsive to changes without the overhead of continuous polling.

Webhook Example

Example of webhook request body configured to include the payload by setting "include_payload": "true" in POST /webhooks request body. If the payroll data comes from uploading a payslip the account_id whould be null but document_external_id and document_filename would be populated is related to uploading a payslip.
{
  "event": "user-payroll-submitted",
  "user_id": "e9b7676b-f107-429c-8d17-cf3fd1362fd3",
  "timestamp": "2024-04-17T13:56:03.277Z",
  "entry_id": "cc48a12c-0e98-47aa-b281-f203403470d0",
  "account_id": "f68961c9-a083-4bfd-a3c6-0ae169b48f35",
  "payload": {
    "entry_id": "cc48a12c-0e98-47aa-b281-f203403470d0",
    "account_id": "f68961c9-a083-4bfd-a3c6-0ae169b48f35",
    "payroll_submissions": [
      {
        "id": "0187c66e-e7e5-811c-b006-2232f00f426a",
        "account_id": "f68961c9-a083-4bfd-a3c6-0ae169b48f35",
        "entry_id": "cc48a12c-0e98-47aa-b281-f203403470d0",
        "created_at": "2024-04-17T13:56:03.118Z",
        "document_external_id": null,
        "document_filename": null,
        "source": "Payroll (via Direct Connection)",
        "identity_information": {
          "name": "Jane Doe",
          "date_of_birth": "1990-04-01",
          "address": {
            "street": "123 Main St",
            "county": "Anyshire",
            "city": "Anycity",
            "post_code": "AB12 3CD",
            "country": "Countryland"
          },
          "email": "jane.doe@example.com",
          "phone": "+1234567890",
          "NI_number": "AB123456C",
          "employment_information": {
            "employer_name": "Acme Corp",
            "role": "Software Developer",
            "type": "Full-Time",
            "status": "Active",
            "start_date": "2018-06-01",
            "leave_date": null
          },
          "income_information": {
            "pay_date": "2024-02-15",
            "pay_interval_start": "2024-02-01T00:00:00.000Z",
            "pay_interval_end": "2024-02-15T00:00:00.000Z",
            "pay_frequency": "weekly",
            "earnings": {
              "gross_pay": 2000,
              "net_pay": 1500,
              "base_salary": 1900,
              "bonus": 100
            },
            "deductions": {
              "income_tax": 300,
              "employee_ni": 150,
              "employee_pension": 50,
              "total_deductions": 500
            }
          }
        }
      }
    ]
  }
}

Bank Statement Webhook Example

Example of a user-bank-statement-submitted webhook request body configured with include_payload enabled. The document_external_ids array contains the external IDs provided during upload, if any. When include_payload is enabled, the payload object contains the full bank statement submission data including extracted account information, balances, and transactions.
{
  "event": "user-bank-statement-submitted",
  "user_id": "e9b7676b-f107-429c-8d17-cf3fd1362fd3",
  "timestamp": "2024-04-17T13:56:03.277Z",
  "document_external_ids": ["ext-stmt-2024-01"],
  "payload": {
    "bank_statement_submissions": [
      {
        "id": "95a0e70b-fe02-4f47-aef9-2efff279df71",
        "created_at": "2024-04-17T13:56:03.118Z",
        "document_id": "a9249254-ab10-4a2d-b709-eda95f5ecd59",
        "document_external_id": "ext-stmt-2024-01",
        "document_filename": "hsbc-january-2024.pdf",
        "account_information": {
          "account_holder_name": "JANE DOE",
          "account_number": "12345678",
          "sort_code": "12-34-56",
          "bank_name": "HSBC",
          "iban": null
        },
        "statement_period": {
          "start_date": "2024-01-01",
          "end_date": "2024-01-31"
        },
        "balance_information": {
          "opening_balance": "1,000.00",
          "closing_balance": "1,250.00"
        },
        "transactions": [
          {
            "date": "2024-01-15",
            "description": "Salary Payment",
            "amount": "2,500.00",
            "type": "credit"
          },
          {
            "date": "2024-01-20",
            "description": "Rent",
            "amount": "-1,250.00",
            "type": "debit"
          }
        ],
        "bank_statement_probability": 0.95
      }
    ]
  }
}