📥 Webhooks Overview

Purpose: Automate your workflows with event-driven notifications FlexPay supports real-time webhook notifications for key payroll events. Once configured, webhooks enable your system to automatically react to important changes such as payroll submissions, paystub generation, and bank transfer confirmations. This eliminates the need for constant polling and allows your platform to stay in sync with employee payment activity.

---

Introduction

In modern payroll systems, speed and reactivity are crucial. Rather than having to continuously check for updates (also known as polling), FlexPay offers a more scalable, efficient solution: webhooks. These are automated HTTP callbacks triggered by specific events. When an event occurs—like a paystub being generated or a payroll run being completed—FlexPay sends a JSON payload to a URL you’ve configured. Your application can then process the event in real-time.

This is particularly useful for building integrations that rely on up-to-date financial data. For instance, your system might send an email to employees when their paystub is ready, update a payroll dashboard, or log completed transactions for accounting purposes. All of this can be automated using webhooks.

Before you start, you’ll need to understand:

• Which events FlexPay emits

• How to configure a secure webhook endpoint

• How to acknowledge events properly (using a 200 OK response)

• What happens if your server is down or rejects the event

Webhooks can dramatically reduce the amount of code you need to write for background jobs and polling logic. More importantly, they make your integration feel more responsive and user-friendly. With FlexPay, you can expect webhook delivery within seconds of the triggering event.

Many developers underestimate the power of a good webhook system. By decoupling your backend logic from scheduled polling, you reduce infrastructure strain, improve app performance, and open the door for real-time features.

We'll show you how to:

• Register and verify a webhook URL

• Receive and decode real FlexPay webhook payloads

• Build workflows around events like paystub.generated and payroll.submitted

---

Configuring Your Webhook URL

To start receiving webhooks, you'll need to provide FlexPay with a publicly accessible HTTPS endpoint. You can register this in your developer dashboard under API > Webhooks.

Figure 1. A Standard Register Webhook page in Flexpay with Sample Endpoint URL

Make sure your endpoint:

• Accepts POST requests

• Responds with 200 OK Within 3 seconds

• Is idempotent (can safely handle duplicate events)

You'll also receive a x-flexpay-signature header with each request. Use this to validate the payload (HMAC-SHA256) against your secret key.

⚠️ Warning: If FlexPay doesn't receive a successful 200 OK, it will retry delivery up to 3 times. Failure beyond that will suppress the webhook. Monitor your logs to prevent silent failures.

---

Sample Event Payload

When FlexPay sends a webhook, the payload contains:

• event_type (e.g. paystub.generated)

• timestamp

• resource (payload data like paystub details)

{
  "event_type": "paystub.generated",
  "timestamp": "2024-04-15T10:30:00Z",
  "resource": {
    "employee_id": "EMP123",
    "payroll_id": "PR456",
    "net_pay": 1800,
    "issued_date": "2024-04-16"
  }
}

Figure 2. Sample webhook payload structure visualized as JSON preview in webhook debugger

Figure 2. Sample webhook payload structure visualized as JSON preview in webhook debugger in FlexPay

Above, you can see how it looks in the FlexPay app.

You can decode the payload and store it in your system for further processing. If needed, associate it with internal records from 👵 Add Employee or 💵 Submit Payroll.

---

Handling Webhook Events

Every webhook must be acknowledged with a 200 OK HTTP status code. Failing to do so will result in retries. We recommend keeping your handler logic fast and queuing any heavy processing in background jobs.

Example webhook handler (Node.js):

app.post("/webhooks/flexpay", (req, res) => {
  const event = req.body;

  if (event.event_type === "paystub.generated") {
    logPaystub(event.resource);
  }

  res.status(200).send("OK");
});

Once you’ve built and tested your webhook logic, your app can start responding to payroll events as they happen.

✅ Summary

You’ve now seen how webhooks bring real-time intelligence into your FlexPay integration. With just a secure URL and some lightweight code, your system can react to critical events like paystub generation and payroll submissions. This makes your application faster, more efficient, and easier to maintain. Instead of writing complicated polling scripts, your app simply waits for FlexPay to notify it.

We also explored security and reliability, confirming payload signatures, returning timely acknowledgments, and building idempotent endpoints. If you’ve already configured employees using ➕ Add Employee and submitted pay using 💵 Submit Payroll, webhooks are the next step to go from manual checks to real-time automation.

---

🔄 What’s Next: 📘 Sample JSON Responses

Now that your app is listening for live events, it's helpful to understand what actual FlexPay responses look like in practice. In the next section, we’ll review full-length sample JSON responses for:

• Creating an employee

• Submitting payroll

• Retrieving paystubs

• Receiving a webhook

📣 Hint: Each sample will include the field names, value types, and nested objects you’ll encounter across endpoints. These are useful for validation and integration tests.

️➡️ Continue to Sample JSON Responses