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

# Configure Webhook

> Sets or updates the URL where your organization receives webhook events.

<Prompt description="Configure Webhook" actions={["cursor"]}>
  Add the Zapyd "Configure Webhook" call (`POST /org/api/v1/organizations/api-webhooks`) to my backend. Sets or updates the URL where your organization receives webhook events.

  * Sandbox: `POST https://sandbox.zapyd.com/org/api/v1/organizations/api-webhooks`
  * Production: `POST https://api.zapyd.com/org/api/v1/organizations/api-webhooks`

  JSON body:

  * `webhook_url` (string, required): The HTTPS URL where webhook events will be sent. Example: `https://yourapp.com/webhooks/zapyd`.

  Success: HTTP 200, `{status: true, message, data}`.
  Errors (`{status: false, message, err_code, errors}`):

  * 400 `Webhook URL is required`
  * 500 `Internal Server Error`
    Every endpoint can also return 401 `AUTH_*` (signature, timestamp or key: fix, don't retry), and 429 or 5xx (retry with backoff).

  Rules:

  * Registers one public HTTPS URL that receives every event type. There's no per-event subscription. Call it once per environment (sandbox and production).
  * Also write the webhook handler: verify `X-TIMESTAMP` (within 300 seconds) and `X-SIGNATURE` before reading the body. The signature uses your own API key and secret, exactly like request signing: Base64(HMAC-SHA256(secret, apiKey + "|" + X-TIMESTAMP + "|" + canonicalJson(parsed body))). Compare in constant time; reject with 401.
  * Envelope: `{type, id, event, timestamp, metadata}`. `id` is the object's Zapyd ID. Events by `type`: CUSTOMER `VERIFIED`/`FAILED` (metadata.failure\_reason); BANK `VERIFIED`/`FAILED`; PAYIN `SUCCESS` (metadata.transaction\_hash, transaction\_reference\_id), `FAILED`, `REFUND_INITIATED`, `REFUNDED`, `ON_HOLD`; PAYOUT `SUCCESS` (metadata.utr), `IN_REVIEW` (metadata.reason, rfi\_link), `FAILED`, `REFUNDED`, each with metadata.client\_reference\_id; EDD `VERIFIED`/`FAILED`. `PROCESSING` is never sent.
  * Return 2xx within a few seconds and process asynchronously. The same event can arrive more than once: store `id` + `event` and skip duplicates. Fetch the full object by `id` when you need more than the envelope.
  * Local development: expose your server with a tunnel such as ngrok and register that URL in sandbox.

  Signing (every request):

  * Headers: `X-API-KEY`, `X-TIMESTAMP` (Unix seconds, within 300 s of server time; generate per request) and `X-SIGNATURE`.
  * `X-SIGNATURE` = Base64(HMAC-SHA256(key = API secret, message = apiKey + "|" + timestamp + "|" + canonicalBody)). Base64 of the raw digest, not hex.
  * canonicalBody: the JSON body with keys sorted at every nesting level, no whitespace (separators `,` and `:`), and every non-ASCII character escaped as lowercase `\uXXXX` (Python `json.dumps(body, sort_keys=True, separators=(",", ":"))`). Requests with no body (GET, DELETE) sign `{}`. Query parameters are not signed.
  * Send the exact canonicalBody string you signed as the request body, with `Content-Type: application/json`.
  * Test vector: key `3f1b2c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d`, secret `test-secret-do-not-use`, timestamp `1735689600`. Signing `{}` gives `6sCtVSRQjU9+2/af8gdwUAvY1l6Ii6ENcbRfanPkhY0=`. Body `{"customer_id":"78c99d71-f28f-47a9-8302-93b286efbe0e","amount":100.5,"currency":"INR","meta":{"note":"Café","b":2,"a":1}}` gives `l+DvQrzlKbsOSxSYOdWoWHEehcFRZfDJPKlLDkm2cSI=`.

  Deliver:

  1. A typed `configureWebhook` function in this codebase's language and HTTP client. Reuse an existing Zapyd client and signer, or write one small shared client.
  2. Config from `ZAPYD_API_KEY`, `ZAPYD_API_SECRET` and `ZAPYD_BASE_URL`. The secret stays on the server, never in a browser or app.
  3. Return `data`. When `status` is false, throw an error with the HTTP status, `err_code`, `message` and `errors`. Don't show raw errors to end users.
  4. Retry only 429 and 5xx: exponential backoff from 1 s, capped at 30 s, at most 5 attempts.
  5. Amounts as strings. Types for every field above.
  6. Tests: the signer against the test vector, and this call against sandbox.

  Reference: `https://docs.zapyd.com/api-reference-exchange/endpoint/organizations/api-webhooks.md`
</Prompt>

| API Status Code | Response | Reason |
| - | - | - |
| 400 | Webhook URL is required | Webhook URL is required |
| 500 | Internal Server Error | Internal Server Error |


## OpenAPI

````yaml POST /organizations/api-webhooks
openapi: 3.1.0
info:
  title: Zapyd API
  description: API for Zapyd - Customer, Payout, and Webhook services
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://sandbox.zapyd.com/pos/api/v1
    description: Payout API Base URL
    variables:
      base_url:
        default: https://sandbox.zapyd.com
  - url: https://sandbox.zapyd.com/cms/api/v1
    description: Customer API Base URL
    variables:
      base_url:
        default: https://sandbox.zapyd.com
security:
  - ApiKeyAuth: []
    TimestampAuth: []
    SignatureAuth: []
tags:
  - name: Customer
    description: Customer related operations
    x-displayName: Customer
    x-traitTag: true
  - name: Payout
    description: Payout related operations
  - name: Webhooks
    description: Webhook related operations
  - name: Widget
    description: Hosted buy/sell widget session initialization
paths:
  /organizations/api-webhooks:
    post:
      tags:
        - Webhook
      description: Configure the webhook URL for receiving transaction status updates
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - webhook_url
              properties:
                webhook_url:
                  type: string
                  format: uri
                  description: The HTTPS URL where webhook events will be sent
                  example: https://yourapp.com/webhooks/zapyd
      responses:
        '200':
          description: Webhook URL configured successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Webhook url updated
                  data:
                    type: string
                    example: https://api.yourapp.com/webhooks/zapyd
                    description: The webhook URL now registered
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                    example: false
                  message:
                    type: string
                    example: Internal Server Error
                  data:
                    type: 'null'
                  err_code:
                    type: string
                    example: SYS_INTERNAL_ERROR
                  errors:
                    type: string
                    example: Unexpected error occurred. Please try again later.
      servers:
        - url: https://sandbox.zapyd.com/org/api/v1
          description: Webhook API Base URL
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
      description: API Key for authentication
    TimestampAuth:
      type: apiKey
      in: header
      name: X-TIMESTAMP
      description: Current timestamp in seconds since epoch
    SignatureAuth:
      type: apiKey
      in: header
      name: X-SIGNATURE
      description: HMAC SHA256 signature of the request encoded in Base64

````

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