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

# Create a webhook

> Registers a new HTTPS endpoint to receive event deliveries. OMS generates
a signing secret (`whsec_` prefix) that is returned **once** in this
response and never again - store it in your secrets manager immediately.
The endpoint starts receiving deliveries immediately after creation.



## OpenAPI

````yaml /api-reference/openapi.yaml post /webhooks
openapi: 3.0.3
info:
  title: Polygon OMS Public API
  version: v26.05.28-0001
  description: >-
    Unified API for moving money between crypto and fiat. Three ways to move
    money: Transactions (instant, wallet or card funded, including Cash-In for
    in-person cash deposits), Deposit Addresses (reusable crypto deposit
    configurations), and Virtual Accounts (dedicated bank accounts that
    auto-convert fiat to crypto). Standard transactions follow a two-step flow:
    create a Quote (pricing), then create a Transaction (execution). Cash-in
    codes generate a one-time deposit code for in-person cash deposits at retail
    locations.
  contact:
    name: Polygon OMS
    url: https://oms.polygon.technology
servers:
  - url: https://sandbox-api.polygon.technology/v0.9
    description: Sandbox
  - url: https://api.polygon.technology/v0.9
    description: Production
security:
  - BearerAuth: []
tags:
  - name: Auth
    description: Authentication via FrontEgg
  - name: Customers
    description: Customer management and KYC
  - name: Customer
  - name: Wallet
  - name: Quote
  - name: Transaction
  - name: Webhook
  - name: CashIns
  - name: CashLocation
  - name: Sandbox
  - name: Simulation
paths:
  /webhooks:
    post:
      tags:
        - Webhook
      summary: Create a webhook
      description: >-
        Registers a new HTTPS endpoint to receive event deliveries. OMS
        generates

        a signing secret (`whsec_` prefix) that is returned **once** in this

        response and never again - store it in your secrets manager immediately.

        The endpoint starts receiving deliveries immediately after creation.
      operationId: createWebhook
      parameters:
        - $ref: '#/components/parameters/IdempotencyKeyHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookCreateRequest'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
          description: >-
            The request has succeeded and a new resource has been created as a
            result.
components:
  parameters:
    IdempotencyKeyHeader:
      description: >-
        Required on POST and PUT requests. Use a unique value per logical
        mutation attempt, for example a UUID.
      in: header
      name: Idempotency-Key
      required: true
      schema:
        type: string
  schemas:
    WebhookCreateRequest:
      properties:
        events:
          description: >-
            Event types to subscribe to. Omit the field, pass `[]`, `["*"]`, or

            `["ALL"]` to subscribe to all events. Specific event type strings
            must

            match the catalog in the webhook delivery documentation.
          items:
            type: string
          type: array
        url:
          description: HTTPS endpoint URL. HTTP is only accepted in local/sandbox mode.
          type: string
      required:
        - url
      type: object
    Webhook:
      properties:
        complianceOnly:
          description: >-
            When true, this endpoint receives compliance-only events (e.g.
            underReview)

            that are excluded from all regular partner webhooks (AML
            no-tipping-off).

            Can only be set via the admin API.
          type: boolean
        createdAt:
          description: ISO 8601 UTC timestamp of when the webhook was registered.
          format: date-time
          type: string
        enabled:
          description: >-
            Whether OMS is actively delivering events to this endpoint. Set to
            `false`

            to pause deliveries without deleting the endpoint. OMS also sets
            this to

            `false` automatically if the endpoint returns `410 Gone`.
          type: boolean
        events:
          description: >-
            Event types this endpoint subscribes to. An empty array means the
            endpoint

            receives all event types (wildcard). See the event catalog in the
            webhook

            delivery documentation for the full list of valid values.
          items:
            type: string
          type: array
        id:
          description: Unique webhook identifier. Uses the `whk_` prefix.
          type: string
        object:
          description: Resource type discriminator. Always `"webhook"`.
          enum:
            - webhook
          type: string
        secret:
          description: >-
            Signing secret used to verify the `Webhook-Signature` header on
            incoming

            deliveries. Uses the `whsec_` prefix (32 cryptographically random
            bytes,

            hex-encoded). **Returned only on creation** - it cannot be retrieved

            afterward. Store it in your secrets manager immediately.
          type: string
        status:
          $ref: '#/components/schemas/WebhookStatus'
        url:
          description: HTTPS endpoint that OMS delivers event payloads to.
          type: string
      required:
        - complianceOnly
      type: object
    WebhookStatus:
      enum:
        - active
        - disabled
      type: string
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Token from POST /auth/token

````