Create webhook | ListBee

import requests
url = "https://api.listbee.so/v1/webhooks"
payload = {
    "name": "Order notifications",
    "url": "https://example.com/webhooks/listbee",
    "events": ["order.paid"]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())

{
  "id": "wh_3mK8nP2qR5tW7xY1",
  "name": "Order notifications",
  "url": "https://example.com/webhooks/listbee",
  "secret": "whsec_a1b2c3d4e5f6",
  "events": [
    "order.paid"
  ],
  "enabled": true,
  "readiness": {
    "ready": true,
    "actions": [
      {
        "code": "connect_stripe",
        "kind": "api",
        "message": "Set Stripe secret key to accept payments",
        "resolve": {
          "method": "POST",
          "endpoint": "/v1/account/stripe-key",
          "url": "https://console.listbee.so/connect/stripe",
          "params": {
            "secret_key": "sk_live_..."
          }
        }
      }
    ]
  },
  "created_at": "2026-04-01T09:00:00Z",
  "object": "webhook"
}

Register a webhook endpoint. Returns the endpoint with its signing secret — store it, shown once. All order events (order.paid, order.fulfilled, order.refunded, order.disputed, order.dispute_closed, order.canceled) include a full order snapshot in the payload: order_id, listing_id, listing_slug, buyer_email, amount, currency, status, content_type, payment_status, checkout_data, timestamps, and deliverable info. Agents never need a follow-up API call after receiving a webhook. See the WebhookPayloadExample schema for the full payload shape.

Authentication

AuthorizationBearer

API key (lb_ prefix). Pass as: Authorization: Bearer lb_...

Request

This endpoint expects an object.

namestringRequired

A name to help you identify this endpoint in the dashboard

urlstringRequiredformat: "uri"1-2083 characters

The HTTPS URL that will receive POST requests for each event

eventslist of enumsOptional

Event types to subscribe to. Empty = all events. Available: order.paid, order.fulfilled, order.shipped, order.refunded, order.disputed, order.dispute_closed, order.canceled, listing.created, listing.updated, listing.out_of_stock, listing.deleted.

Response

Successful Response

idstring

Unique identifier

namestring

Display name

urlstring

Endpoint URL

secretstring

HMAC-SHA256 signing secret. Use to verify webhook payload signatures. See docs for verification examples.

eventslist of enums

Subscribed event types. Empty means all events

enabledboolean

false when delivery is paused

readinessobject

Readiness status with actionable steps if the webhook needs attention.

created_atdatetime

Time at which the endpoint was created

object"webhook"

Object type identifier. Always webhook.

disabled_reasonstring or null

Reason the webhook was disabled. consecutive_failures when auto-disabled after repeated delivery failures.

Errors

401

Unauthorized Error

422

Unprocessable Entity Error