> ## Documentation Index
> Fetch the complete documentation index at: https://developers.paychoice.com.au/llms.txt
> Use this file to discover all available pages before exploring further.

# Register a webhook

Registers a webhook URL for the merchant. PayChoice then POSTs a notification to it when a charge is created and whenever its status changes — card or bank, API or Widget.

> [!WARNING]
>
> `webhook_secret` is the HMAC-SHA256 key for the `X-Webhook-Signature` header and is **only returned by this call**. Store it securely.

A merchant-level credential can only register for its own merchant GUID. See the [Webhooks guide](https://developers.paychoice.com.au/getting-the-result/webhooks.md) for payload format and signature verification.

```json 201 theme={null}
{
  "id": "0f6a1c2d-8e4b-4a7c-9d3e-5b2f1a6c8d90",
  "merchant_guid": "315564b9-b863-4016-8c53-02c9d8cc80b7",
  "webhook_url": "https://your-app.example.com/paychoice/webhook",
  "webhook_secret": "c2VjcmV0LXNlY3JldC1zZWNyZXQtc2VjcmV0LXNlY3JldA==",
  "created_date": "2026-11-04T02:30:00.000Z",
  "updated_date": null,
  "updated_by": null,
  "active": true
}
```

The registration object is returned directly, with no envelope.

**id** `uuid`

The registration ID. Needed for Update.

**webhook\_secret** `string`

44-character Base64 string. Use it as-is as the HMAC key; do not decode it.

**active** `boolean`

Whether notifications are being sent.


## OpenAPI

````yaml POST /api/v5/merchantwebhooks
openapi: 3.0.1
info:
  title: Paychoice
  version: v5
servers: []
security:
  - basic: []
paths:
  /api/v5/merchantwebhooks:
    post:
      tags:
        - MerchantWebhook
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMerchantWebhookRequestDto'
          text/json:
            schema:
              $ref: '#/components/schemas/CreateMerchantWebhookRequestDto'
          application/*+json:
            schema:
              $ref: '#/components/schemas/CreateMerchantWebhookRequestDto'
      responses:
        '200':
          description: OK
components:
  schemas:
    CreateMerchantWebhookRequestDto:
      type: object
      properties:
        merchant_guid:
          type: string
          format: uuid
        webhook_url:
          type: string
          nullable: true
      additionalProperties: false
  securitySchemes:
    basic:
      type: http
      description: Basic Authorization header using the Bearer scheme.
      scheme: basic

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.