openapi: 3.0.0
info:
  title: Webhooks
  description: Webhooks allow your application to receive real-time notifications from Zoho Payments when specific events occur, such as successful payments or failed refunds. Use the Webhooks API to register and manage webhook endpoints, subscribe to events, and verify incoming payloads using the signing key generated for each webhook. For a list of supported events and sample payloads, refer to the <a href="/us/payments/api/v1/webhooks-events/">Webhook Events documentation</a>.
  contact: {}
  version: 1.0.0
servers:
  - url: https://payments.zoho.com/api/v1
    description: API Endpoint
tags:
  - name: webhooks
    description: Webhooks Module
paths:
  /webhooks:
    post:
      tags:
        - webhooks
      summary: Create Webhook
      operationId: create-webhook
      description: This API registers a new webhook endpoint that will receive notifications for the events you subscribe to. The <code>signing_key</code> returned in the response is shown only at creation; store it securely so you can verify webhook signatures.
      parameters:
        - $ref: '#/components/parameters/account_id'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/webhook-create-request'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/webhook-create-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoPay.settings.CREATE
    get:
      tags:
        - webhooks
      summary: List Webhooks
      operationId: list-webhooks
      description: This API returns the list of webhook endpoints configured for your Zoho Payments account.
      parameters:
        - $ref: '#/components/parameters/account_id'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/webhook-list-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoPay.settings.READ
  /webhooks/{webhook_url_id}:
    get:
      tags:
        - webhooks
      summary: Retrieve Webhook
      operationId: retrieve-webhook
      description: This API returns the details of a specific webhook endpoint, including its subscribed events.
      parameters:
        - name: webhook_url_id
          description: The unique identifier of the webhook.
          in: path
          required: true
          schema:
            type: string
          example: '1987000000724219'
        - $ref: '#/components/parameters/account_id'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/webhook-retrieve-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoPay.settings.READ
    put:
      tags:
        - webhooks
      summary: Update Webhook
      operationId: update-webhook
      description: |
        This API updates a webhook endpoint. The <code>enabled_events</code> list is required and replaces the webhook's current event subscriptions. You can also update the <code>url</code>, <code>name</code>, and <code>description</code> in the same request.
        <br><br>
        To <b>pause</b> or <b>resume</b> the webhook, include <code>webhook_status</code> set to <code>inactive</code> or <code>active</code> in the same request.
      parameters:
        - name: webhook_url_id
          description: The unique identifier of the webhook.
          in: path
          required: true
          schema:
            type: string
          example: '1987000000724219'
        - $ref: '#/components/parameters/account_id'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/webhook-update-request'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/webhook-update-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoPay.settings.UPDATE
    delete:
      tags:
        - webhooks
      summary: Delete Webhook
      operationId: delete-webhook
      description: This API permanently deletes a webhook endpoint. Deleted endpoints stop receiving event notifications and cannot be restored. To temporarily disable event delivery, set the webhook status to <code>inactive</code> using the Update Webhook API.
      parameters:
        - name: webhook_url_id
          description: The unique identifier of the webhook.
          in: path
          required: true
          schema:
            type: string
          example: '1987000000724219'
        - $ref: '#/components/parameters/account_id'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/webhook-delete-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoPay.settings.DELETE
components:
  parameters:
    account_id:
      name: account_id
      description: The Zoho Payments account ID.
      in: query
      required: true
      schema:
        type: string
      example: '23137556'
  schemas:
    gendoc-attributes-schema:
      $ref: '#/components/schemas/webhook-resource'
    webhook_url_id:
      description: The unique identifier of the webhook.
      type: string
      example: '1987000000724219'
    name:
      description: A descriptive name for the webhook endpoint. Maximum 50 characters.
      type: string
      example: Payment notifications
    url:
      description: The HTTPS URL of your server that will receive webhook event deliveries.
      type: string
      example: https://example.com/zohopayments/webhook
    description:
      description: An optional description of what this webhook is used for.
      type: string
      example: Forwards payment and refund events to our order management system.
    status:
      description: The current status of the webhook endpoint. Possible values are <code>active</code> (delivering events), <code>inactive</code> (paused by you and no events are delivered), and <code>disabled</code> (set by Zoho Payments when your account is suspended). Only <code>active</code> webhooks are moved to <code>disabled</code> during suspension, while <code>inactive</code> webhooks are not affected. When the suspension is revoked, a <code>disabled</code> webhook is automatically restored to <code>active</code>.
      type: string
      example: active
    signing_key:
      description: The HMAC-SHA256 signing key used to verify the authenticity of incoming webhook events. It is returned only when the webhook is created via the API. Store it securely and you can also view it later in the Zoho Payments web app. Learn how to <a href="https://www.zoho.com/us/payments/developerdocs/webhooks/verification/" target="_blank">verify the signature</a>.
      type: string
      example: 52402c8bd2edb946a072d13e0599ef992ad661a54e4a472385c394185cfb0d2597b88415891c11356c83a739be74b5797bf8dfbacc7a80c00bc6a2f5bb74e2d49a841b172fc78069237cbffe38ddc15b
    enabled_events:
      description: The list of event types this webhook is subscribed to. Refer to the <a href="/us/payments/api/v1/webhooks-events/">Webhook Events documentation</a> for the supported events and their payloads.
      type: array
      items:
        type: string
      example:
        - payment.succeeded
        - payment.failed
        - refund.succeeded
    webhook-event-group:
      type: object
      properties:
        entity_type:
          description: The entity that the events belong to (for example, <code>payment_link</code>, <code>refund</code>, <code>payout</code>).
          type: string
          example: payment_link
        event_types:
          description: The subscribed event names for this entity.
          type: array
          items:
            type: string
          example:
            - payment_link.paid
            - payment_link.canceled
        entity_type_formatted:
          description: The display name of the entity.
          type: string
          example: Payment Link
    webhook_events:
      description: The events this webhook is subscribed to, grouped by entity type. Returned in list responses.
      type: object
      properties:
        total_events:
          description: The total number of events this webhook is subscribed to.
          type: integer
          example: 4
        events:
          description: The subscribed events, grouped by entity type.
          type: array
          items:
            $ref: '#/components/schemas/webhook-event-group'
          example:
            - entity_type: payment_link
              event_types:
                - payment_link.paid
                - payment_link.canceled
              entity_type_formatted: Payment Link
            - entity_type: refund
              event_types:
                - refund.succeeded
                - refund.failed
              entity_type_formatted: Refund
    created_time:
      description: The timestamp (epoch seconds) when the webhook endpoint was created.
      type: integer
      format: int64
      example: 1708950672
    webhook_status:
      description: The status to set for the webhook. Accepted values are <code>active</code> (resume event delivery) and <code>inactive</code> (pause event delivery). Optional — include it in an Update Webhook request only when you want to change the status.
      type: string
      example: active
    webhook-resource:
      type: object
      properties:
        webhook_url_id:
          $ref: '#/components/schemas/webhook_url_id'
        name:
          $ref: '#/components/schemas/name'
        url:
          $ref: '#/components/schemas/url'
        description:
          $ref: '#/components/schemas/description'
        status:
          $ref: '#/components/schemas/status'
        signing_key:
          $ref: '#/components/schemas/signing_key'
        enabled_events:
          $ref: '#/components/schemas/enabled_events'
        created_time:
          $ref: '#/components/schemas/created_time'
    webhook-resource-no-secret:
      type: object
      properties:
        webhook_url_id:
          $ref: '#/components/schemas/webhook_url_id'
        name:
          $ref: '#/components/schemas/name'
        url:
          $ref: '#/components/schemas/url'
        description:
          $ref: '#/components/schemas/description'
        status:
          $ref: '#/components/schemas/status'
        enabled_events:
          $ref: '#/components/schemas/enabled_events'
        created_time:
          $ref: '#/components/schemas/created_time'
    webhook-list-item:
      type: object
      properties:
        webhook_url_id:
          $ref: '#/components/schemas/webhook_url_id'
        name:
          $ref: '#/components/schemas/name'
        status:
          $ref: '#/components/schemas/status'
        url:
          $ref: '#/components/schemas/url'
        description:
          $ref: '#/components/schemas/description'
        created_time:
          $ref: '#/components/schemas/created_time'
        webhook_events:
          $ref: '#/components/schemas/webhook_events'
    webhook-create-request:
      required:
        - name
        - url
        - enabled_events
      type: object
      example:
        name: Payment notifications
        url: https://example.com/zohopayments/webhook
        description: Forwards payment and refund events to our order management system.
        enabled_events:
          - payment.succeeded
          - payment.failed
          - refund.succeeded
      properties:
        name:
          $ref: '#/components/schemas/name'
        url:
          $ref: '#/components/schemas/url'
        description:
          $ref: '#/components/schemas/description'
        enabled_events:
          $ref: '#/components/schemas/enabled_events'
    webhook-update-request:
      required:
        - enabled_events
      type: object
      description: The <code>enabled_events</code> list is required. Optionally include <code>name</code>, <code>url</code>, <code>description</code>, and <code>webhook_status</code> to update them in the same call.
      example:
        name: Payment notifications
        url: https://example.com/zohopayments/webhook-v2
        description: Updated payment webhook endpoint.
        enabled_events:
          - payment.succeeded
          - payment.failed
          - payment.pending
          - refund.succeeded
          - refund.failed
        webhook_status: active
      properties:
        name:
          $ref: '#/components/schemas/name'
        url:
          $ref: '#/components/schemas/url'
        description:
          $ref: '#/components/schemas/description'
        enabled_events:
          $ref: '#/components/schemas/enabled_events'
        webhook_status:
          $ref: '#/components/schemas/webhook_status'
    webhook-create-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
          readOnly: true
        message:
          type: string
          example: Webhook added successfully
          readOnly: true
        webhook_url:
          $ref: '#/components/schemas/webhook-resource'
    webhook-retrieve-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
          readOnly: true
        message:
          type: string
          example: success
          readOnly: true
        webhook_url:
          $ref: '#/components/schemas/webhook-resource-no-secret'
    webhook-list-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
          readOnly: true
        message:
          type: string
          example: success
          readOnly: true
        webhook_url:
          type: object
          properties:
            webhook_urls:
              type: array
              items:
                $ref: '#/components/schemas/webhook-list-item'
    webhook-update-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
          readOnly: true
        message:
          type: string
          example: Webhook updated successfully
          readOnly: true
        webhook_url:
          $ref: '#/components/schemas/webhook-resource-no-secret'
    webhook-delete-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
          readOnly: true
        message:
          type: string
          example: WebhookURL deleted successfully
          readOnly: true
  securitySchemes:
    Zoho_Auth:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: https://accounts.zoho.com/oauth/v2/auth
          scopes:
            ZohoPay.settings.CREATE: Create Webhooks
            ZohoPay.settings.READ: Retrieve Webhooks
            ZohoPay.settings.UPDATE: Update Webhooks
            ZohoPay.settings.DELETE: Delete Webhooks
