Webhooks

​

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.
• No more events are supported at the moment.

​

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",
    "secret": "very-secret",
    "url": "https://webhooks.site"
  }'

• events: Choose events like user-payroll-submitted for targeted notifications.
• name: Label your webhook for easier management.
• url: Your endpoint to receive webhook payloads.
• secret: (Optional) A secret for secure webhook verification.

​

Verifying Webhooks

If the optional secret was provided in the webhook subscription, it can be used to validate incoming webhook signatures, ensuring data integrity and authenticity.

To verify if a received webhook event is authentic:

• Encode the webook payload with the 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 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:

​

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 secret confidential and use it to verify webhook payloads.
• 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,
        "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-01",
            "pay_interval_end": "2024-02-15",
            "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
            }
          }
        }
      }
    ]
  }
}