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

# Register Webhook

> Register a new webhook endpoint to receive event notifications. Webhooks are created with `status: "disabled"` by default and must be enabled using the PUT endpoint. For comprehensive webhook setup and verification guides, see [Configure Webhooks](/documentation/getting-started/configure-webhook) and [Webhook Verification](/documentation/developer-platform/monitoring/webhook-verification).



## OpenAPI

````yaml /api-reference/openapi.json post /onboarding/api/v1/webhooks
openapi: 3.0.0
info:
  title: Carbn Connect API
  version: 1.0.0
  description: >-
    API documentation for Carbn Connect services including user onboarding, KYC,
    wallet management, and transfers.
servers:
  - url: https://api.carbnconnect.com
    description: Production server
security:
  - ApiKeyAuth: []
paths:
  /onboarding/api/v1/webhooks:
    post:
      tags:
        - Webhook Management
      summary: Register Webhook
      description: >-
        Register a new webhook endpoint to receive event notifications. Webhooks
        are created with `status: "disabled"` by default and must be enabled
        using the PUT endpoint. For comprehensive webhook setup and verification
        guides, see [Configure
        Webhooks](/documentation/getting-started/configure-webhook) and [Webhook
        Verification](/documentation/developer-platform/monitoring/webhook-verification).
      operationId: registerWebhook
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookRegisterRequest'
      responses:
        '200':
          description: Webhook registered successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookRegisterResponse'
        '400':
          description: Invalid request - URL must be HTTPS or invalid event category
        '401':
          description: Unauthorized - API key is missing or invalid
      security:
        - ApiKeyAuth: []
components:
  schemas:
    WebhookRegisterRequest:
      type: object
      required:
        - url
        - event_category
      properties:
        url:
          type: string
          format: uri
          pattern: ^https://.*
          example: https://testmywebhook.requestcatcher.com/test
          description: >-
            The HTTPS URL where webhook events will be sent. Must use HTTPS
            protocol.
        event_category:
          type: string
          enum:
            - ONRAMP_TRANSACTION_STATUS
            - OFFRAMP_TRANSACTION_STATUS
            - USER_STATUS_UPDATE
            - CUSTODY_WALLET_TRANSACTION
          example: ONRAMP_TRANSACTION_STATUS
          description: >-
            The category of events this webhook should receive. Allowed values:
            ONRAMP_TRANSACTION_STATUS (onramp/fiat-to-crypto transfer status
            updates), OFFRAMP_TRANSACTION_STATUS (offramp/crypto-to-fiat
            transfer status updates), USER_STATUS_UPDATE (user KYC/onboarding
            status changes), CUSTODY_WALLET_TRANSACTION (custody wallet transfer
            status updates).
    WebhookRegisterResponse:
      type: object
      properties:
        public_key:
          type: string
          example: |-
            -----BEGIN PUBLIC KEY-----
            MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...
            -----END PUBLIC KEY-----
          description: >-
            PEM-formatted public key for webhook signature verification. Use
            this key to verify the authenticity of webhook events sent to your
            endpoint.
        id:
          type: string
          format: uuid
          example: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
          description: Unique identifier for the registered webhook
        event_category:
          type: string
          example: ONRAMP_TRANSACTION_STATUS
          description: The event category for this webhook
        url:
          type: string
          format: uri
          example: https://testmywebhook.requestcatcher.com/test
          description: The registered webhook URL
        status:
          type: string
          enum:
            - enabled
            - disabled
          example: disabled
          description: Current status of the webhook (created as 'disabled' by default)
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API key for authentication. Must be included in the x-api-key header.

````