> For the complete documentation index, see [llms.txt](https://docs.switchappgo.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.switchappgo.com/webhooks.md).

# Webhooks

SwitchApp initiates calls to your webhook endpoints configured on your dashboard or provided on the transaction/request body itself. Webhook-enabled actions include payments, top-ups, disbursements, and payouts.

Each webhook call includes an event property that describes the status change. This can be used to configure your system's reaction to the webhook call.

The example below simulates the possible endpoints in a merchant's application for handling SwitchApp webhook calls.

{% hint style="warning" %}
NOTE: All webhook endpoints should be unprotected i.e. they must not require authentication to be called, as these calls are coming from SwitchApp servers which will not authenticate on the merchant servers.
{% endhint %}

## Sample Merchant Payment Webhook Endpoint

Payment webhook events include the following

* ```
  charge.successful
  ```
* ```
  charge.partial
  ```
* ```
  charge.failed
  ```
* ```
  charge.abandoned
  ```
* ```
  charge.refunded
  ```
* ```
  charge.pending
  ```

{% openapi src="/files/kb87EQmBh95XRQb3iF1g" path="/v1/sample-switchapp-merchant-webhooks/sample-v1-switchapp-payments-webhooks" method="post" %}
[switchapp-webhooks-sample-swagger.json](https://163660187-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F8qcR8TOKMHOvHEJFAJcO%2Fuploads%2FgJJikkTPJYElycrJowFM%2Fswitchapp-webhooks-sample-swagger.json?alt=media\&token=cd6af136-44dd-4744-8c75-e8b63aa74403)
{% endopenapi %}

## Sample Merchant Top-Up Webhook Endpoint

Top-up webhook events include the following

* ```
  topup.successful
  ```

{% openapi src="/files/kb87EQmBh95XRQb3iF1g" path="/v1/sample-switchapp-merchant-webhooks/sample-v1-switchapp-topups-webhooks" method="post" %}
[switchapp-webhooks-sample-swagger.json](https://163660187-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F8qcR8TOKMHOvHEJFAJcO%2Fuploads%2FgJJikkTPJYElycrJowFM%2Fswitchapp-webhooks-sample-swagger.json?alt=media\&token=cd6af136-44dd-4744-8c75-e8b63aa74403)
{% endopenapi %}

## Sample Merchant Disbursement Webhook Endpoint

Disbursement webhook events include the following

* transfer.successful
* transfer.failed
* transfer.awaitingAuthorization
* transfer.authorizationFailed

{% openapi src="/files/kb87EQmBh95XRQb3iF1g" path="/v1/sample-switchapp-merchant-webhooks/sample-v1-switchapp-transfers-webhooks" method="post" %}
[switchapp-webhooks-sample-swagger.json](https://163660187-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F8qcR8TOKMHOvHEJFAJcO%2Fuploads%2FgJJikkTPJYElycrJowFM%2Fswitchapp-webhooks-sample-swagger.json?alt=media\&token=cd6af136-44dd-4744-8c75-e8b63aa74403)
{% endopenapi %}