# Webhooks overview

Product: PNSL API
Guides follow API reference 2.0.0 and event reference 1.0.0.
Canonical page: https://docs.axiym.io/pnsl-api/webhooks/overview

Webhooks notify your service when a PNSL resource changes. Axiym sends an
HTTP `POST` with a signed JSON event to a URL you register.

## How it works

1. **Register an endpoint.** Give Axiym the HTTPS URL that should receive
   events; see [Register and manage subscriptions](/pnsl-api/webhooks/registration-and-management).
2. **Receive events.** Axiym `POST`s a JSON envelope (`id`, `timestamp`,
   `type`, `data`) whenever a resource changes. Preserve the raw request body
   for verification.
3. **Verify the delivery.** Every delivery is signed with Ed25519 over the raw
   request body; the headers `X-Signature`, `X-Key-Id`, and
   `X-Algorithm: Ed25519` identify the signature and key. See
   [Verify signatures](/pnsl-api/webhooks/verifying-signatures).
4. **Store and acknowledge.** After verification, durably store the event,
   then respond `2XX` to acknowledge it.
5. **Process the event.** Deduplicate by `id` and read the resource for its
   current state.

## Events

| Event                    | What happened                                                  |
| ------------------------ | -------------------------------------------------------------- |
| `client.created`         | An onboarding case was submitted; the client is `ONBOARDING`.  |
| `client.updated`         | A client attribute changed.                                    |
| `client.activated`       | Onboarding was approved; the client is `ACTIVE`.               |
| `client.disabled`        | The client is `DISABLED`.                                      |
| `credit-account.created` | A credit account was provisioned for the client.               |
| `credit-account.updated` | A credit account amount or status changed.                     |
| `receivable.created`     | A funding request was accepted; the receivable is `PENDING`.   |
| `receivable.disbursed`   | The disbursement settled; the receivable is `ACTIVE`.          |
| `receivable.repaid`      | A repayment settled; `currentPrincipal` went down.             |
| `receivable.settled`     | The receivable is fully repaid (`PAID`).                       |
| `receivable.canceled`    | The receivable is `CANCELED`.                                  |
| `subscription.test`      | Sent by `POST /webhooks/subscriptions/{subscriptionId}/tests`. |

`client.onboarding-finished` is a legacy duplicate of `client.activated`; new
integrations can ignore it. Your subscription receives every event Axiym
emits for you, including types not listed here; ignore unknown types.

Payloads and schemas are in the [Events](/pnsl-api/events) reference.

## Delivery

Verify the delivery before durably storing and acknowledging it with `2XX`,
then process it. Deliveries can repeat: acknowledge verified duplicates that
are already stored, but do not process them again. Events report a change;
read the resource for its current state.