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.
You create your test key in the portal as soon as your account is activated.
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 documented events
These are the documented event types, the ones to build your integration on. The contract's enum contains others, not documented here: build nothing on them, and subscribe each endpoint to an explicit list taken from this catalog.
- 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 billing period paid, subscription.payment_failed when a card payment attempt on a period's link fails, and subscription.canceled when a subscription ends. 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 |
Make your first test-mode call
Create your account, generate your test key in the portal and send your first request today — or talk to an integrator.
- Free, no commitment
- Test mode from sign-up
- No approval to wait for