---
title: "Create or update webhook endpoints"
method: POST
path: "/merchants/{merchantId}/webhook"
tags: ["Webhooks"]
---

# Create or update webhook endpoints

`POST /merchants/{merchantId}/webhook`

## Request

- Base URL: `https://sandbox-payouts.peachpayments.com/api`
- URL: `https://sandbox-payouts.peachpayments.com/api/merchants/{merchantId}/webhook`
- Auth: HTTP bearer

Create, update, or remove pre-configured webhook endpoints for payouts and bank account verification notifications, and configure which notification types are sent to the payouts webhook URL.

## Path parameters

- `merchantId` string, required: A unique merchant ID provided by Peach Payments in hexadecimal format.

## Request body

- object
  - `webhookEndpoint` string, uri, nullable: Payouts status notification endpoint. Set to a valid URL to create/update; set to null to remove; omit to leave unchanged.
  - `banvEndpoint` string, uri, nullable: Bank account verification update notification endpoint. Set to a valid URL to create/update; set to null to remove; omit to leave unchanged.
  - `webhookOptions` WebhookOptions: Toggles for which notification types are sent to the payouts webhook URL.
    - `floatAllocationUpdates` boolean: When true, receive webhooks when a deposit is allocated to float (top-up).
    - `payoutStatusUpdates` boolean: When true, receive webhooks when payout status changes.

## Response `200`

Endpoints updated.

- object
  - `webhookEndpoint` string: Echoes the current payouts endpoint (empty string if removed or not configured). Present only if included in the request.
  - `banvEndpoint` string: Echoes the current BANV endpoint (empty string if removed or not configured). Present only if included in the request.
  - `webhookOptions` WebhookOptions: Toggles for which notification types are sent to the payouts webhook URL.
    - `floatAllocationUpdates` boolean: When true, receive webhooks when a deposit is allocated to float (top-up).
    - `payoutStatusUpdates` boolean: When true, receive webhooks when payout status changes.

## Other responses

- `400`: Invalid request body.
- `401`: The request is not authenticated. Please re-authenticate and provide a new token.
- `403`: The request is not authorised. Please contact your business administrator.

---

[API](https://skmtc.dev/peachpayments/apis/payouts.md) - [All operations](https://skmtc.dev/peachpayments/apis/payouts/llms.txt) - [OpenAPI document](https://skmtc.dev/peachpayments/apis/payouts/revisions/a53677a021ef?raw)