Webhooks

Overview

Webhooks enable your application to receive real-time notifications whenever payment events occur in your account. Instead of polling our API for payment status, webhooks push events directly to your server the moment something happens.

Webhooks are the most reliable way to track payment events. Use them to automatically update your system, trigger fulfillment, or send confirmation emails.

How Webhooks Work

When a payment-related event occurs in our system, we send an HTTP POST request to your configured webhook URL. Your server should respond with a 200 OK status to acknowledge receipt.

Event Types

Invoice Events

Event	Description
`invoice.created`	Payment initiated, invoice created
`invoice.overdue`	Payment deadline passed without payment
`invoice.cancelled`	User cancelled the invoice/subscription

Payment Events

Event	Description
`payment.confirmed`	Payment confirmed with enough confirmations and amount

Subscription Events

Event	Description
`subscription.overdue`	Subscription renewal deadline passed without payment

Use payment.confirmed as your primary fulfillment trigger. This ensures payment is fully confirmed before you deliver service.

Quick Setup

Set your webhook URL in your organization settings via the API or dashboard.

Use your API key to verify incoming webhook requests are authentic.

Process the webhook payload and respond with 200 OK quickly.

Retry Policy

If your server returns a non-2xx status code or times out, we will retry the webhook:

Immediate retry - First attempt after failure
Second attempt - 2 minutes after first retry
Final attempt - 2 minutes after second retry

After 3 failed attempts, the webhook is marked as failed. Ensure your endpoint is reliable and returns 200 OK quickly.

Deadlines

Scenario	Deadline
First payment (one-time or recurring)	1 hour
Recurring cycles (after first payment)	24 hours

After the deadline, invoice.overdue is sent.

Consistent Event Model

All webhook events follow the same structure and include:

Identifier - id, invoiceId, orgId
Amount - amount (formatted), amountUsd (USD equivalent)
Type - paymentType (ONE_TIME or RECURRING)
Status - Current state of the invoice/payment
Customer - Customer info for fulfilling orders