> This page is for Cash App Pay Partner API.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.cash.app/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.cash.app/_mcp/server.

### Schema (`response.body`)

```yaml
openapi: 3.1.0
info:
  title: API
  version: 1.0.0
paths:
  /webhook-endpoints:
    post:
      operationId: subpackageWebhooks_create-webhook-endpoint
      summary: Create webhook endpoint
      description: |-
        Creates a new webhook endpoint which Cash App can send events to.

        <Note title="Note">
         Webhook events will not be successfully delivered for new domains until the new domain is allow-listed. New domains must be manually reviewed and allow-listed. It will typically take 1 business day to allow-list new domains.
        </Note>

        Scopes: `WEBHOOK_CONFIG_WRITE`
      tags:
        - subpackage_webhooks
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/webhooks_create-webhook-endpoint_Response_201
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                idempotency_key:
                  $ref: '#/components/schemas/IdempotencyKey'
                webhook_endpoint:
                  $ref: >-
                    #/components/schemas/WebhookEndpointsPostRequestBodyContentApplicationJsonSchemaWebhookEndpoint
              required:
                - idempotency_key
                - webhook_endpoint
tags:
  - name: subpackage_webhooks
servers:
  - url: https://api.cash.app/management/v1
    description: Production
  - url: https://sandbox.api.cash.app/management/v1
    description: Sandbox
components:
  schemas:
    IdempotencyKey:
      type: string
      minLength: 1
      maxLength: 64
      description: >-
        A unique identifier which can be used by Cash App to de-duplicate
        retries of this request, making it idempotent. Learn more about
        [idempotency](../docs/api/technical-documentation/api-fundamentals/idempotency)
        in the API.
      title: IdempotencyKey
    EventType:
      type: string
      enum:
        - customer.created
        - customer.deleted
        - customer.updated
        - customer_request.state.updated
        - dispute.created
        - dispute.state.updated
        - grant.created
        - grant.status.updated
        - merchant.status.updated
        - payment.status.updated
        - refund.status.updated
      description: The type of event that will be sent to the webhook endpoint.
      title: EventType
    ApiVersion:
      type: string
      enum:
        - v1
      description: 'Represents the API version. '
      title: ApiVersion
    EventConfiguration:
      type: object
      properties:
        event_type:
          $ref: '#/components/schemas/EventType'
        api_version:
          $ref: '#/components/schemas/ApiVersion'
      required:
        - event_type
        - api_version
      description: >-
        Represents a supported event type and the API version that the event of
        this type should be serialized to.
      title: EventConfiguration
    WebhookEndpointsPostRequestBodyContentApplicationJsonSchemaWebhookEndpoint:
      type: object
      properties:
        api_key_id:
          type: string
          minLength: 1
          maxLength: 128
          description: >-
            The API key ID which will be used to sign requests made to this
            webhook endpoint.
        event_configurations:
          type: array
          items:
            $ref: '#/components/schemas/EventConfiguration'
          description: >-
            The list of supported event types for this webhook endpoint. Events
            of a particular type will only be sent to endpoints that contain the
            type in this list.
        url:
          type:
            - string
            - 'null'
          description: >-
            The URL of the endpoint which events will be delivered to. If NULL
            is specified, events will be not be delivered to an endpoint but
            will still be persisted and accessible via the List Webhook Events
            API.
        reference_id:
          type: string
          minLength: 1
          maxLength: 1024
          description: >-
            A user-defined identifier for this webhook endpoint, typically used
            to associate the webhook endpoint with a record in an external
            system.
        delivery_timeout:
          type: number
          format: double
          minimum: 1000
          maximum: 10000
          default: 5000
          description: >-
            The duration, in milliseconds, that Cash App will take to deliver an
            event to this endpoint before timing out.
        max_delivery_frequency:
          type: number
          format: double
          minimum: 1
          maximum: 100000
          description: >-
            The maximum number of events per second that will be delivered to
            this endpoint before rate limiting kicks in. The default for this
            field is unset (NULL) which means no rate limiting. However, if you
            enable rate limiting, the values can range from 1 to 100000.
      required:
        - api_key_id
        - event_configurations
        - url
      title: >-
        WebhookEndpointsPostRequestBodyContentApplicationJsonSchemaWebhookEndpoint
    WebhookEndpointStatus:
      type: string
      enum:
        - APPROVED
        - ENDPOINT_URL_UNDER_REVIEW
      description: >-
        The approval status of a webhook endpoint. Once a webhook endpoint is
        approved, Cash App will deliver events to that webhook endpoint.
      title: WebhookEndpointStatus
    WebhookEndpoint:
      type: object
      properties:
        id:
          type: string
          minLength: 1
          maxLength: 128
          description: The unique ID for a webhook endpoint issued by Cash App.
        api_key_id:
          type: string
          minLength: 1
          maxLength: 128
          description: >-
            The API key ID which will be used to sign requests made to this
            webhook endpoint.
        reference_id:
          type: string
          minLength: 1
          maxLength: 1024
          description: >-
            A user-defined identifier for this webhook endpoint, typically used
            to associate the webhook endpoint with a record in an external
            system.
        url:
          type:
            - string
            - 'null'
          format: uri
          description: >-
            The events are delivered to this endpoint URL. If NULL, events will
            be not be delivered to an endpoint but will still be persisted and
            accessible via the List Webhook Events API.
        event_configurations:
          type: array
          items:
            $ref: '#/components/schemas/EventConfiguration'
          description: >-
            The list of supported event types for this webhook endpoint. Events
            of a particular type will only be sent to endpoints that contain the
            type in this list.
        created_at:
          type: string
          format: date-time
          description: The timestamp of when this webhook endpoint was created.
        updated_at:
          type: string
          format: date-time
          description: The timestamp of when this endpoint was last updated.
        delivery_timeout:
          type: number
          format: double
          minimum: 1000
          maximum: 10000
          default: 5000
          description: >-
            The duration, in milliseconds, that Cash App will take to deliver an
            event to this endpoint before timing out.
        max_delivery_frequency:
          type:
            - number
            - 'null'
          format: double
          minimum: 1
          maximum: 100000
          description: >-
            The maximum number of events per second that will be delivered to
            this endpoint before rate limiting kicks in. The default for this
            field is unset (NULL) which means no rate limiting. However, if you
            enable rate limiting, the values can range from 1 to 100000.
        status:
          $ref: '#/components/schemas/WebhookEndpointStatus'
      required:
        - id
        - api_key_id
        - url
        - event_configurations
        - created_at
        - updated_at
        - delivery_timeout
        - status
      description: The events will be sent to this webhook endpoint.
      title: WebhookEndpoint
    webhooks_create-webhook-endpoint_Response_201:
      type: object
      properties:
        webhook_endpoint:
          $ref: '#/components/schemas/WebhookEndpoint'
      required:
        - webhook_endpoint
      title: webhooks_create-webhook-endpoint_Response_201
    ErrorCategory:
      type: string
      enum:
        - API_ERROR
        - AUTHENTICATION_ERROR
        - BRAND_ERROR
        - DISPUTE_ERROR
        - MERCHANT_ERROR
        - INVALID_REQUEST_ERROR
        - PAYMENT_PROCESSING_ERROR
        - RATE_LIMIT_ERROR
        - WEBHOOK_ERROR
        - API_KEY_ERROR
        - GRANT_ERROR
      description: The high-level reason the error occurred
      title: ErrorCategory
    Error:
      type: object
      properties:
        category:
          $ref: '#/components/schemas/ErrorCategory'
          description: The high-level reason the error occurred
        code:
          type: string
          description: >-
            A unique identifier for the specific type of error that occurred.
            See the Error Code Reference for more information.


            Min length: `1`
        detail:
          type: string
          description: >-
            Human-readable description of why the error occurred and how to
            resolve it.


            Min length: `1`
        field:
          type: string
          description: >-
            The field in the request that caused the error, using array and
            object dot notation.


            Min length: `1`
      required:
        - category
        - code
      description: Represents an error encountered during a request to the API.
      title: Error
    ErrorResponse:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: |-
            A list of errors that occurred while processing the request.

            Min number of items: `1`
      required:
        - errors
      title: ErrorResponse

```

**`Example`**

```json Example
{
  "id": "WC_2f6cd0d5cc26b34ac8785026b149797ecc0758be3dc3a857d405f2f62074ef30",
  "api_key_id": "string",
  "reference_id": "string",
  "url": "http://example.com",
  "event_configurations": [
    {
      "event_type": "customer.created",
      "api_version": "v1"
    }
  ],
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "delivery_timeout": 5000,
  "max_delivery_frequency": null,
  "status": "APPROVED"
}
```