Webhook endpoints

Signed notifications the aggregator pushes to your server when payments and

disbursements change state. No rail pushes events — the aggregator synthesizes

them, so webhooks are the reliable way to learn a payment finished.

Platform-wide concepts (auth, idempotency, versioning, errors) live on the

Register an endpoint

`POST /webhook-endpoints`

Request:


POST /webhook-endpoints
Authorization: Bearer sk_test_...
Content-Type: application/json

{ "url": "https://you.example.com/hooks/transxact" }

Response (200):


{
  "endpoint": {
    "id": "ep_...",
    "url": "https://you.example.com/hooks/transxact",
    "secret": "whsec_..."
  }
}

The secret is returned once only — store it. An endpoint is marked

active only after it answers the one-off webhook.verified event with a 2xx;

delivery to an unverified endpoint is skipped.

Manage endpoints

`GET /webhook-endpoints`

List registered endpoints (IDs and URLs, never secrets).

`DELETE /webhook-endpoints/{id}`

Delete an endpoint.

`POST /webhook-endpoints/{id}/rotate`

Issue a new signing secret; the old secret shadows it for 72h before it stops

verifying.

Verify deliveries

Each delivery carries:

Transxact-Signature: v1=<hex> header
Transxact-Timestamp header (Unix seconds)
X-Transxact-Event-Id header

The signature is HMAC-SHA256("<timestamp>.<body>") computed with your

endpoint secret. Reject any delivery whose timestamp is older than 5 minutes

(replay window). Deduplicate on event_id — retries re-send the same id.

Events

Event	When sent
`webhook.verified`	Once, after registration or secret rotation
`payment.processing`	Intent reaches `processing`
`payment.succeeded`	Intent reaches `succeeded`
`payment.failed`	Intent reaches `failed`
`disbursement.sent`	After the daily disbursement run
`disbursement.failed`	A disbursement bounces

Payloads are additive and unversioned: fields are only ever added, receivers

must not reject unknown fields (ADR-0013).

Code examples:

Language	Example
Python	`transxact.webhook_endpoints.create({"url": "https://you.example.com/hooks/transxact"})`
Node.js	`await transxact.webhookEndpoints.create({ url: "https://you.example.com/hooks/transxact" })`

Related: Payment intents — the objects

these events describe.