10 endpoints
Webhooks
Your receiving URLs, their signing secrets, the list of emitted events and the detail of every delivery.
Endpoint names and descriptions come from the OpenAPI contract, in English — they cannot drift from the API.
In plain English
The signed notifications ChariPay sends to your server.
When to use it
From the very first payment. Without webhooks, your system will never reliably know that a payment succeeded.
How to integrate it
- 1Declare a URL with the explicit list of events you care about.
- 2Collect the signing secret and keep it like an API key.
- 3Send a test event to check your receiving end works, end to end.
- 4Read the delivery log when an event seems missing — it says whether we sent it, and what your server answered.
- 5Rotate the secret periodically, and reactivate an endpoint we may have suspended after too many failures.
The events actually emitted
These are the only event types the API sends. Other values appear in the contract's enum: they are reserved and never fire — subscribing to one gives you a branch of code that never runs.
- Payments
payment.succeededpayment.failedorder.paid
- Subscriptions
subscription.payment_succeededsubscription.payment_failedsubscription.canceled
- Refunds
refund.succeededrefund.failed
- Account movements
merchant_transfer.completedmerchant_transfer.failedtopup.succeededtopup.failedbill_payment.pendingbill_payment.succeededbill_payment.failed
- Distribution
wallet.activatedwallet.rejectedpayout.completedpayout.failedsubmerchant.near_cap
- GET
/api/v1/partner/webhooks/endpointsList partner webhook endpoints - POST
/api/v1/partner/webhooks/endpointsRegister a partner webhook endpoint - POST
/api/v1/partner/webhooks/endpoints/{id}/testSend a test event to a partner webhook endpoint - POST
/api/v1/partner/webhooks/endpoints/{id}/rotate-secretRotate a partner webhook signing secret - POST
/api/v1/partner/webhooks/endpoints/{id}/activateReactivate a suspended partner webhook endpoint - GET
/api/v1/partner/webhooks/endpoints/{id}Retrieve a partner webhook endpoint - PATCH
/api/v1/partner/webhooks/endpoints/{id}Update a partner webhook endpoint - DELETE
/api/v1/partner/webhooks/endpoints/{id}Delete a partner webhook endpoint - GET
/api/v1/partner/webhooks/eventsList emitted webhook events - GET
/api/v1/partner/webhooks/events/{deliveryId}Retrieve one emitted webhook event
List partner webhook endpoints
| Field | Type | In | Required | Description |
|---|---|---|---|---|
pageable | Pageable | query | Required |
Register a partner webhook endpoint
Returns the signing secret once; it is not exposed by later reads. Store it in a secret manager. The endpoint belongs only to the API key's SANDBOX or PRODUCTION environment. Subscribe to subscription.payment_succeeded to mark a merchant billing period paid, subscription.payment_failed for normalized recovery information, and subscription.canceled for terminal dunning. Events include ExternalId, PeriodDate and merchant metadata for reconciliation.
Schema · WebhookEndpointRequest
| Field | Type | In | Required | Description |
|---|---|---|---|---|
url | string | body | Required | Public HTTPS receiver URL on port 443. Private, loopback, link-local and non-HTTPS targets are rejected. |
description | string | body | Optional | Merchant-facing endpoint label. |
enabledEvents | array of enum | body | Optional | Explicit event allowlist. Null or empty subscribes to every current and future event; an explicit list is recommended for stable integrations. |
customHeaders | object | body | Optional | Optional static routing headers. Host, Authorization, Cookie, Chari-* and X-CHARI-* cannot be overridden. |
apiVersion | string | body | Optional | Webhook payload contract version. |
enabled | boolean | body | Optional | Whether delivery starts immediately. |
environment | enum | body | Optional | SANDBOX or PRODUCTION. Portal routes only — defaults to PRODUCTION when omitted. Ignored on /api/v1/partner/** where the API key decides, and ignored on update (an endpoint cannot move between environments; delete and re-create instead).Values SANDBOXPRODUCTION |
Send a test event to a partner webhook endpoint
Queues a synthetic payment.succeeded carrying Test: true, signed exactly like a real event, ignoring the event allowlist. Returns the delivery id; read it back on GET /api/v1/partner/webhooks/events/{deliveryId} to see your receiver's response.
| Field | Type | In | Required | Description |
|---|---|---|---|---|
id | string (uuid) | path | Required |
Rotate a partner webhook signing secret
Immediately invalidates the previous secret and returns the replacement once. Update the receiver atomically to avoid rejecting deliveries.
| Field | Type | In | Required | Description |
|---|---|---|---|---|
id | string (uuid) | path | Required |
Reactivate a suspended partner webhook endpoint
Endpoints are auto-suspended after repeated delivery failures; queued events are retained and resume in order on reactivation.
| Field | Type | In | Required | Description |
|---|---|---|---|---|
id | string (uuid) | path | Required |
Retrieve a partner webhook endpoint
| Field | Type | In | Required | Description |
|---|---|---|---|---|
id | string (uuid) | path | Required |
Update a partner webhook endpoint
Updates the URL, explicit event allowlist, custom routing headers, or enabled state. Use an explicit enabledEvents list to avoid automatically receiving newly introduced events.
Schema · WebhookEndpointRequest
| Field | Type | In | Required | Description |
|---|---|---|---|---|
id | string (uuid) | path | Required | |
url | string | body | Required | Public HTTPS receiver URL on port 443. Private, loopback, link-local and non-HTTPS targets are rejected. |
description | string | body | Optional | Merchant-facing endpoint label. |
enabledEvents | array of enum | body | Optional | Explicit event allowlist. Null or empty subscribes to every current and future event; an explicit list is recommended for stable integrations. |
customHeaders | object | body | Optional | Optional static routing headers. Host, Authorization, Cookie, Chari-* and X-CHARI-* cannot be overridden. |
apiVersion | string | body | Optional | Webhook payload contract version. |
enabled | boolean | body | Optional | Whether delivery starts immediately. |
environment | enum | body | Optional | SANDBOX or PRODUCTION. Portal routes only — defaults to PRODUCTION when omitted. Ignored on /api/v1/partner/** where the API key decides, and ignored on update (an endpoint cannot move between environments; delete and re-create instead).Values SANDBOXPRODUCTION |
Delete a partner webhook endpoint
| Field | Type | In | Required | Description |
|---|---|---|---|---|
id | string (uuid) | path | Required |
List emitted webhook events
Returns the events emitted for this API key's environment, newest first. Filter by endpoint, event type, delivery status or creation window. Event types use their dotted value such as payment.succeeded; the full catalog is available from GET /api/v1/partner/webhooks/event-types. Payloads are omitted here — read a single event to get the exact signed body.
| Field | Type | In | Required | Description |
|---|---|---|---|---|
endpointId | string (uuid) | query | Optional | |
eventType | enum | query | Optional | Values payment_link.createdpayment_link.updatedpayment_link.expiredpayment_link.cancelledpayment.initiatedpayment.requires_actionpayment.succeededpayment.failedsubscription.payment_succeededsubscription.payment_failedsubscription.canceledrefund.initiatedrefund.succeededrefund.failedsecurity.token_reusedsecurity.rate_limit_exceededsecurity.invalid_signaturewallet.activatedwallet.rejectedpayout.completedpayout.failedsubmerchant.near_capwallet.fundedwallet.transfer_completedmerchant_transfer.completedmerchant_transfer.failedtopup.pendingtopup.succeededtopup.failedtopup.reversedbill_payment.pendingbill_payment.succeededbill_payment.failedbill_payment.reversedvoucher.issuedvoucher.failedvoucher.redeemedvoucher.expiredsavings.deposit_succeededsavings.withdrawal_succeededsavings.instruction_failedsavings.goal_reachedorder.paid |
status | enum | query | Optional | Values pendingsendingdeliveredfailedretryingexhaustedskipped |
from | string (date-time) | query | Optional | |
to | string (date-time) | query | Optional | |
pageable | Pageable | query | Required |
Retrieve one emitted webhook event
Includes the exact signed payload that was sent to the receiver, which lets a partner reproduce the signature locally before replaying.
| Field | Type | In | Required | Description |
|---|---|---|---|---|
deliveryId | string (uuid) | path | Required |
A question about integration?
Our technical team supports integrators from the first sandbox call through to go-live.