# 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: partners-v1
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.order.created` (boolean)
    Subscribe to sub-merchant order authorization events (Checkout SDK or Partners API)
    Example: true

  - `events.order.updated` (boolean)
    Subscribe to sub-merchant order change events (capture, cancel, detail updates)
    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.payment.created` (boolean)
    Subscribe to payment creation events. Sent for payments processed through Resolve and payments reported as collected outside Resolve; not sent for payments with the credit_note, adjustment or unapplied_payment_adjustment method. A payment held in review is announced once it leaves the in_review status with a customer assigned.
    Example: true

  - `events.payment.status_changed` (boolean)
    Subscribe to payment status change events (for example, pending, in_transit, paid, failed, canceled). Reported payments have no status and never emit this event.
    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

  - `events.merchant.created` (boolean)
    Subscribe to partner-facing sub-merchant creation events
    Example: true

  - `events.merchant.underwriting_completed` (boolean)
    Subscribe to sub-merchant underwriting completion events
    Example: true

  - `events.merchant.more_info_needed` (boolean)
    Subscribe to sub-merchant underwriting needs-info events
    Example: false

  - `events.merchant.mal_updated` (boolean)
    Subscribe to sub-merchant MAL update events
    Example: false

## Request examples:

  - `Subscribe to specific events` (unknown)

  - `Subscribe to sub-merchant order events` (unknown)
    Receive the order ID of every order a buyer authorizes through a sub-merchant's Checkout SDK, as a fallback to the SDK success redirect, plus capture and cancel updates.

  - `Subscribe to partner merchant lifecycle 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 partner 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)

