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.
  • Notifying upon successful account linkages.
  • Triggering actions after data updates.

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.

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

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.