Introduction

Use webhooks to notify your application about kamiPay events.

kamiPay uses webhooks to push real-time notifications to you about a payment receive. All webhooks use HTTPS and deliver a JSON payload that can be used by your application.

Steps to receive webhooks

You can start receiving real-time events in your app using the following steps:

1. Description

The Status Update webhook provides a way to receive events when changes occur in a payment within the system. Whenever a payment change event occurs, a notification will be sent to the client's URL with the content of the affected payment.

2. Delivery Method

The webhook sends events using the HTTP POST method.

3. Event Content

The event content will be a JSON message that includes the details of the payment affected by the change. The message will have the following format:

{
  "pix_id": "168*******878",
  "status": "done",
  "tx_id": "563ce2792b5deff9440b6xxxxxxxxxxxxxxxf0c25b47739cbc3a35b16",
  "timestamp": "2023-08-01T11:00:00+00:00"
}

4. Authentication

The webhook uses message signature-based authentication to ensure the integrity and authenticity of the sent notifications. A secret key must be shared between the client and the provider to generate the message signature.

5. Client-Side Code Example

In your local application, create a new route that can accept POST requests.

For example, you can add an API route on Next.js:

// app/api/webhooks.ts
import crypto from "crypto";
import { headers } from "next/headers";
 
export async function POST(req: Request) {
  // Obtain the X-Kamipay-Auth header value from the webhook response.
  // This header contains the HMAC-SHA256 signature of the webhook payload created using a shared secret key.
  const signature = headers().get("X-Kamipay-Auth");
 
  const body = await req.json();
 
  // Calculate the HMAC-SHA256 signature of the received webhook payload using the same shared secret key.
  const hashBodyEncrypt = crypto
    .createHmac("sha256", "SECRET_KEY")
    .update(JSON.stringify(body))
    .digest("hex");
 
  // Compare the calculated HMAC-SHA256 signature with the value of the X-Kamipay-Auth header.
  // If they match, it indicates that the data has not been tampered with during transmission.
  if (signature !== hashBodyEncrypt) {
    return new Response(`Webhook Error: Unauthorized`, { status: 403 })
  }
 
  return new Response(null, {status: 200});
}

Webhook Types

kamiPay provides two main types of webhooks to track different payment flows. The Charge webhook notifies you when a customer sends a Pix payment. The Pay webhook provides updates about outgoing payments made from your account to third parties. Select one of the options below for detailed specifications: