Webhooks

Account-level webhooks let your customers receive real-time notifications when events happen in their account — a new payment, a usage threshold hit, a user invited, etc. Your customers register their own endpoint URLs and Prime delivers the events automatically.

This is separate from payment webhooks (which are gateway-to-Prime). Account webhooks are Prime-to-customer.

How it works

1. A customer registers a webhook URL via the dashboard or API
2. When an event fires in Prime (e.g. a payment succeeds), the server dispatches a SEND_WEBHOOK job to the queue
3. The job POSTs a JSON payload to the customer's URL
4. Delivery is handled asynchronously via BullMQ / pg-boss — failures don't block the main request

API endpoints

Method	Endpoint	Description
GET	/webhooks/event-types	List all available event types
GET	/webhooks	List all webhooks for the account
GET	/webhooks/:id	Get a single webhook
POST	/webhooks	Create a new webhook
PUT	/webhooks/:id	Update a webhook (URL, events, active state)
DELETE	/webhooks/:id	Delete a webhook

Creating a webhook

POST /webhooks
Authorization: Bearer your_token
Content-Type: application/json

{
  "url": "https://yourcustomer.com/hooks/prime",
  "events": ["payment.success", "account.expired"],
  "active": true
}

Webhook payload

Payloads are delivered as a POST request with a JSON body:

{
  "event": "payment.success",
  "account_id": "acc_abc123",
  "timestamp": "2025-04-05T12:00:00Z",
  "data": {
    ...event-specific fields...
  }
}

Available events

Retrieve the full list at runtime:

GET /webhooks/event-types

Access control

Webhook endpoints require the developer role or higher. Available on all plan tiers: free-tier, standard, premium, and professional.

Delivery

Webhook delivery is handled by the SEND_WEBHOOK queue channel. If delivery fails (non-2xx response or timeout), the job is retried according to your queue driver's retry policy.

See Background Jobs for queue configuration.