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

# Create a webhook configuration

> Registers the webhook endpoint for the authenticated partner.

Configure webhooks before onboarding users so your integration receives
asynchronous status changes. The endpoint must be publicly reachable over
HTTPS and should return a successful response promptly.

Store the returned `public_key` and verify every delivery before processing
it. Each request includes:

- `X-Webhook-Timestamp`: the delivery time as a Unix timestamp in seconds.
- `X-Webhook-Signature`: a standard Base64-encoded Ed25519 signature.

Build the verification payload by concatenating the timestamp header, a
literal `.` character, and the exact raw request body bytes. Base64-decode
the signature and verify it against that payload with the public key. Do not
parse or re-serialize the body before verification. Process event IDs
idempotently because deliveries may repeat.



## OpenAPI

````yaml https://core.sandbox.gnosispay.in/partner-api/openapi.json post /v1/webhooks
openapi: 3.1.0
info:
  title: Gnosis Pay Partner API
  version: 1.0.0
  description: >-
    Server-to-server API for onboarding users, creating accounts and cards,
    moving

    funds, and managing the card lifecycle. Call this API only from a trusted

    backend. Every request requires a partner access token, and every resource
    is

    scoped to the authenticated partner.
servers:
  - url: https://core.prod.gnosispay.com/partner-api
    description: Production
    variables: {}
  - url: https://core.sandbox.gnosispay.in/core
    description: Sandbox
    variables: {}
security:
  - BearerAuth: []
tags:
  - name: Accounts
  - name: Cards
  - name: Card transactions
  - name: KYC
  - name: Deposits
  - name: Withdrawals
  - name: PCI
  - name: 3DS
  - name: Webhooks
paths:
  /v1/webhooks:
    post:
      tags:
        - Webhooks
      summary: Create a webhook configuration
      description: >-
        Registers the webhook endpoint for the authenticated partner.


        Configure webhooks before onboarding users so your integration receives

        asynchronous status changes. The endpoint must be publicly reachable
        over

        HTTPS and should return a successful response promptly.


        Store the returned `public_key` and verify every delivery before
        processing

        it. Each request includes:


        - `X-Webhook-Timestamp`: the delivery time as a Unix timestamp in
        seconds.

        - `X-Webhook-Signature`: a standard Base64-encoded Ed25519 signature.


        Build the verification payload by concatenating the timestamp header, a

        literal `.` character, and the exact raw request body bytes.
        Base64-decode

        the signature and verify it against that payload with the public key. Do
        not

        parse or re-serialize the body before verification. Process event IDs

        idempotently because deliveries may repeat.
      operationId: webhooks.create.v1
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWebhookParams'
        description: Delivery URL and optional description for the webhook.
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookConfigResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    CreateWebhookParams:
      type: object
      required:
        - url
      properties:
        url:
          type: string
          description: Public HTTPS URL where webhook events will be delivered.
        description:
          anyOf:
            - type: string
            - type: 'null'
          description: Optional description for your own reference.
      description: Parameters for creating a webhook configuration.
    WebhookConfigResponse:
      type: object
      required:
        - data
      properties:
        data:
          $ref: '#/components/schemas/WebhookConfig'
          description: Current webhook configuration.
    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: integer
          format: int32
          description: HTTP status code.
        message:
          type: string
          description: Generic human-readable text for the status code. Do not parse it.
        reason:
          type: string
          description: >-
            Stable machine-readable code identifying the specific cause, present
            only

            for errors that expose one (e.g. `CREATE_CARD_LIMIT_EXCEEDED`).
            Branch on

            this rather than on `message`.
    WebhookConfig:
      type: object
      required:
        - id
        - url
        - status
        - description
        - public_key
        - created_at
        - updated_at
      properties:
        id:
          $ref: '#/components/schemas/uuid'
          description: Unique identifier of the webhook configuration.
        url:
          type: string
          description: HTTPS endpoint that receives webhook events.
        status:
          $ref: '#/components/schemas/WebhookConfigStatus'
          description: Whether event delivery is active or paused.
        description:
          anyOf:
            - type: string
            - type: 'null'
          description: Optional description supplied by the partner.
        public_key:
          type: string
          description: >-
            PEM-encoded Ed25519 public key used to verify signatures in the
            `X-Webhook-Signature` header.
        created_at:
          type: string
          format: date-time
          description: When the configuration was created.
        updated_at:
          type: string
          format: date-time
          description: When the configuration was last updated.
      description: Webhook configuration for receiving event notifications.
    uuid:
      type: string
      format: uuid
    WebhookConfigStatus:
      type: string
      enum:
        - active
        - paused
  securitySchemes:
    BearerAuth:
      type: http
      scheme: Bearer

````

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