Get Started
Back to Docs

Webhooks

Receive real-time notifications about payment events via webhooks.

What are Webhooks?

Webhooks allow you to receive real-time notifications when specific events happen in your Yeld account.

Configure webhook endpoints in your dashboard settings

Setting Up Webhooks

  1. Navigate to Dashboard → Settings → Webhooks
  2. Click "Add Webhook Endpoint"
  3. Enter your webhook URL (must be HTTPS)
  4. Select which events to subscribe to
  5. Save and copy the webhook secret

Store your webhook secret securely. It's only shown once during setup.

Event Types

Subscribe to specific events to receive targeted notifications.

payment.createdEmitted when a new payment is initiated

{
  "id": "evt_abc123",
  "type": "payment.created",
  "data": {
    "checkoutLinkId": "uuid",
    "businessId": "uuid",
    "planId": "plan_abc123",
    "amount": "50.00",
    "currency": "USDC",
    "network": "base-sepolia"
  },
  "createdAt": "2024-01-01T00:00:00Z"
}
payment.confirmedEmitted when a payment is confirmed on-chain

{
  "id": "evt_def456",
  "type": "payment.confirmed",
  "data": {
    "checkoutSessionId": "uuid",
    "txHash": "0x7890abcdef...",
    "amount": "50.00",
    "senderAddress": "0x1234567890abcdef...",
    "blockNumber": 12345678
  },
  "createdAt": "2024-01-01T00:01:00Z"
}
payment.failedEmitted when a payment fails

{
  "id": "evt_ghi789",
  "type": "payment.failed",
  "data": {
    "checkoutSessionId": "uuid",
    "error": "Insufficient funds",
    "txHash": "0xabcdef1234..."
  },
  "createdAt": "2024-01-01T00:02:00Z"
}

Code Examples

Implement webhook handlers in your application.

Express.js Handler

import express from "express";
import { createHmac, randomBytes } from "crypto";

const app = express();
app.use(express.raw({ type: "application/json" }));

app.post("/webhooks/yeld", (req, res) => {
  const signature = req.headers["x-yeld-signature"];
  const payload = req.body;

  // Verify signature
  const expectedSignature = createHmac("sha256", process.env.YELD_WEBHOOK_SECRET)
    .update(payload)
    .digest("hex");

  if (signature !== expectedSignature) {
    return res.status(400).send("Invalid signature");
  }

  const event = JSON.parse(payload.toString());

  switch (event.type) {
    case "payment.confirmed":
      console.log(`Payment confirmed: ${event.data.txHash}`);
      // Update your database, send confirmation email, etc.
      break;
    case "payment.failed":
      console.log(`Payment failed: ${event.data.error}`);
      break;
  }

  res.status(200).json({ received: true });
});

Next.js Route Handler

import { NextRequest, NextResponse } from "next/server";
import { createHmac } from "crypto";

export async function POST(request: NextRequest) {
  const signature = request.headers.get("x-yeld-signature");
  const payload = await request.text();

  // Verify signature
  const expectedSignature = createHmac("sha256", process.env.YELD_WEBHOOK_SECRET)
    .update(payload)
    .digest("hex");

  if (signature !== expectedSignature) {
    return NextResponse.json({ error: "Invalid signature" }, { status: 400 });
  }

  const event = JSON.parse(payload);

  switch (event.type) {
    case "payment.confirmed":
      await handlePaymentConfirmed(event.data);
      break;
    case "payment.failed":
      await handlePaymentFailed(event.data);
      break;
  }

  return NextResponse.json({ received: true });
}

async function handlePaymentConfirmed(data: any) {
  // Your logic here
  console.log(`Payment confirmed for${data.planId}`);
}

Security Best Practices

  • Verify Signatures

    Always verify the \`x-yeld-signature\` header using your webhook secret to ensure the request is from Yeld.

  • Use HTTPS

    Webhook endpoints must use HTTPS to ensure data is encrypted in transit.

  • Handle Retries

    Yeld retries failed webhook deliveries up to 5 times with exponential backoff. Make your handler idempotent.

  • Timeouts

    Your webhook handler should respond within 5 seconds. Process long-running tasks asynchronously.

Testing Webhooks

Use the webhook testing tools in your dashboard to verify your integration.

  • Send test events from the dashboard
  • View delivery logs for each webhook
  • Configure test mode for development
SDKs & Libraries →