# Create or update webhook endpoints

Create a new webhook endpoint or update an existing one. If an endpoint with the same URL already exists, it will be updated with the new event subscriptions.

Endpoint: POST /webhooks
Version: V5
Security: bearerAuth, basicAuth

## Security:

  - `bearerAuth` (unknown)
    http bearer JWT

  - `basicAuth` (unknown)
    http basic

## Request fields (application/json):

  - `endpoint_url` (string, required)
    The HTTPS URL where webhook events will be sent. Must use HTTPS protocol.
    Example: https://example.com/webhooks/resolve

  - `events` (object, required)
    Object containing boolean flags for each available webhook event topic. Set to true to subscribe to that event, or false to unsubscribe.

  - `events.invoice.created` (boolean)
    Subscribe to invoice creation events
    Example: true

  - `events.invoice.balance_updated` (boolean)
    Subscribe to invoice balance update events
    Example: false

  - `events.customer.created` (boolean)
    Subscribe to customer creation events
    Example: true

  - `events.customer.status_updated` (boolean)
    Subscribe to customer status update events
    Example: false

  - `events.customer.line_amount_updated` (boolean)
    Subscribe to customer credit line amount update events
    Example: false

  - `events.customer.advance_rate_updated` (boolean)
    Subscribe to customer advance rate update events
    Example: false

  - `events.customer.credit_decision_created` (boolean)
    Subscribe to customer credit decision creation events
    Example: true

  - `events.order.created` (boolean)
    Subscribe to order creation events
    Example: false

  - `events.order.updated` (boolean)
    Subscribe to order update events
    Example: false

  - `events.payment.created` (boolean)
    Subscribe to payment creation events
    Example: true

  - `events.payment.status_changed` (boolean)
    Subscribe to payment status change events
    Example: true

  - `events.payout.created` (boolean)
    Subscribe to payout creation events
    Example: false

  - `events.payout.status_changed` (boolean)
    Subscribe to payout status change events
    Example: false

## Request examples:

  - `Subscribe to specific events` (unknown)

  - `Unsubscribe from specific events` (unknown)
    Update an existing endpoint to unsubscribe from certain event types by setting them to false. Only events set to true will remain active.

## Response 200:

  - `200` (unknown)
    Successful response with webhook endpoint subscriptions

## Response 200 fields (application/json):

  - `id` (string)
    Unique identifier for the webhook endpoint
    Example: whe_abc123def456

  - `merchant_id` (string)
    The merchant ID associated with this webhook endpoint
    Example: mer_xyz789

  - `endpoint_url` (string)
    The HTTPS URL where webhook events will be sent
    Example: https://example.com/webhooks/resolve

  - `topic` (object)
    The event topic this endpoint is subscribed to

  - `topic.name` (string)
    The event topic name
    Example: invoice.created

  - `topic.description` (string)
    Human-readable description of the event topic
    Example: Triggered when a new invoice record is created

  - `created_at` (string)
    When this webhook endpoint subscription was created
    Example: 2021-05-20T09:23:53+00:00

  - `updated_at` (string)
    When this webhook endpoint subscription was last updated
    Example: 2021-05-20T09:23:53+00:00

## Response 400:

  - `400` (unknown)
    Bad request error

## Response 400 fields (application/json):

  - `error` (object)

  - `error.message` (string)
    A short string, describing error details
    Example: Validation error

  - `error.type` (string)
    A short string, describing error type
    Enum: "validation_error"

  - `error.details` (array)

  - `error.details.path` (string)
    Path to the field failed validation
    Example: path.to.field

  - `error.details.message` (string)
    Detailed description of the error
    Example: `[field]` is required

## Response 401:

  - `401` (unknown)
    Unauthorized error

## Response 401 fields (application/json):

  - `error` (object)

  - `error.message` (string)
    A short string, describing error details
    Example: Invalid merchant credentials

  - `error.type` (string)
    A short string, describing error type
    Enum: "authentication_error"

## Response 429:

  - `429` (unknown)
    Rate limit error

## Response 429 fields (application/json):

  - `error` (object)

  - `error.message` (string)
    A short string, describing error details
    Example: Too many requests

  - `error.type` (string)
    A short string, describing error type
    Enum: "rate_limit_error"

## Response 200 examples:

  - `Newly created webhook endpoint subscriptions` (unknown)

  - `Updated webhook endpoint with new event subscriptions` (unknown)