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 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:
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});
}