Webhooks

Payments are event-driven. Once you create a payout, it may take seconds or days to complete depending on the payment method and banking networks involved. Webhooks let you:

Update internal records when payouts succeed or fail.
Trigger notifications to your team or payees.
Automate reconciliation and reporting.

Setting Up a Webhook Endpoint

A webhook endpoint is just an HTTPS URL on your server that can accept POST requests.

When something happens — like a payout completing — Acclaim sends a JSON payload to your endpoint.

Key considerations when building your endpoint:

Must accept POST requests with a JSON body.
Must return a 2xx HTTP status code to acknowledge receipt.
Should be idempotent (able to safely handle duplicate deliveries).

Example flow:

Acclaim sends an event payload to your webhook URL.
Your server processes the event.
Your server responds with 200 OK to confirm receipt.

Installing Webhooks in the Console

You can install and manage webhook endpoints directly from the Acclaim Console under Settings → Webhooks.

Add one or more HTTPS URLs where Acclaim should send events.
Choose which event types to subscribe to, or receive all events by default.
Test delivery right from the console to verify your endpoint is working.

Event Payload Structure

All webhook events share a consistent format:

{
  "id": "evt_12345",
  "type": "payout.completed",
  "created_at": "2025-10-08T18:20:31Z",
  "data": {
    "object": {
      "id": "po_789",
      "amount": 50000,
      "currency": "usd",
      "payee_id": "py_456"
    }
  }
}

id — Unique event identifier.
type — Event type, such as payout.completed.
created_at — Timestamp of the event.
data.object — The resource that changed (e.g., payout details).

Common Event Types

While the full list evolves, here are some typical events to expect:

Event	Description
`payout.created`	A payout was created successfully.
`payout.processing`	A payout has started processing.
`payout.succeeded`	Funds have reached the payee.
`payout.failed`	A payout could not be completed.
`wallet.transaction.created`	A wallet’s balance changed (e.g., after funding or payout).
`payee.created`	A new payee record was added.
`payout_batch.completed`	A payout batch has finished processing.

Reliability & Retries

Acclaim automatically retries failed webhook deliveries for up to 48 hours using exponential backoff.

Your endpoint should:

Be idempotent: safely handle duplicate events.
Respond quickly: return 2xx as soon as the event is accepted, then process asynchronously if needed.
Log event ids to avoid reprocessing the same event.

If all retry attempts fail, the event will be marked as undelivered in the Acclaim Console.

Securing Webhooks

Webhooks should be secure so only Acclaim can call them:

Use HTTPS for encryption.
Validate the Authorization header or signature (coming soon).
Optionally whitelist Acclaim’s IP ranges.

Future versions of Acclaim will include signing secrets to cryptographically verify payload authenticity.