Create a webhook endpoint

POST/v1/webhook-endpointsRun

Requires webhooks:write permission.

Request body

scopestringoptional

project receives events from one project; merchant receives events from every project of the account.

Example: project

Possible values: project, merchant

project_idstringoptional

The project of a project endpoint; null for a merchant endpoint.

Example: prj_01k7q3m8x2v5t9n4b6c1d0e7fa

Prefixed with prj_.

urlstringrequired

The public HTTPS address Baiyar calls with each event.

Example: https://toko.example.com/webhooks/baiyar

Min length: 8

Max length: 2048

descriptionstringoptional

An internal label to tell this endpoint apart from your other webhook endpoints.

Example: Server produksi

Min length: 1

Max length: 200

eventsarray of stringoptional

The event types or patterns it follows, such as payment.*. Empty means every event.

Max items: 40

Response (201)

dataobjectrequired

The returned object, or an array of objects for a list.

idstringrequired

The id of the endpoint (whk_…).

Example: whk_01k7q3m8x2v5t9n4b6c1d0e7fa

Prefixed with whk_.

livemodebooleanrequired

true means this object belongs to live and can involve real payments; false means it belongs to the sandbox.

scopestringrequired

project receives events from one project; merchant receives events from every project of the account.

Example: project

Possible values: project, merchant

project_idstring | nullrequired

The project of a project endpoint; null for a merchant endpoint.

Example: prj_01k7q3m8x2v5t9n4b6c1d0e7fa

Prefixed with prj_.

urlstringrequired

The public HTTPS address Baiyar calls with each event.

Example: https://toko.example.com/webhooks/baiyar

descriptionstring | nullrequired

An internal label to tell this endpoint apart from your other webhook endpoints.

Example: Server produksi

eventsarray of stringrequired

The event types or patterns it follows, such as payment.*. Empty means every event.

statusstringrequired

active, disabled (switched off by you) or auto_disabled (switched off after repeated failures).

Example: active

Possible values: active, disabled, auto_disabled

disabled_reasonstring | nullrequired

Why delivery was stopped. Null while the endpoint is active.

Example: string

consecutive_failuresintegerrequired

How many deliveries in a row used all their tries. At 5 the endpoint is switched off.

Example: 0

secretsarray of objectrequired

Signing secrets currently accepted for webhook signatures. Two appear during rotation; only the last four characters are shown.

last4stringrequired

The last four characters of the secret, to tell them apart. The secret itself is never shown again.

Example: Xk3a

statusstringrequired

active, or retiring (still signs for a day after a rotation).

Example: active

Possible values: active, retiring

retire_atstring | nullrequired

When a retiring secret stops signing; null for the active one.

Example: 2026-10-26T03:04:05.000Z

Format: date-time

created_atstringrequired

When this object was created (RFC 3339, UTC). Use it to sort objects by creation time.

Example: 2026-10-26T03:04:05.000Z

Format: date-time

secretstringrequired

The signing secret, whsec_…. It is in this answer only: store it now.

Example: whsec_k3f9…

metaobjectrequired

Request details such as its id and pagination cursor.

request_idstringrequired

The id of this request. Quote it when you ask support about it.

Example: req_Hy3k9QzT2LmN8vXa

A failed request answers with the common error shape; see Errors.

Request

curl -X POST "https://api.baiyar.com/v1/webhook-endpoints" \
  -H "Authorization: Bearer $BAIYAR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://toko.example.com/webhooks/baiyar",
    "description": "Server produksi"
  }'

Response

{
  "data": {
    "id": "whk_01k7q3m8x2v5t9n4b6c1d0e7fa",
    "livemode": false,
    "scope": "project",
    "project_id": "prj_01k7q3m8x2v5t9n4b6c1d0e7fa",
    "url": "https://toko.example.com/webhooks/baiyar",
    "description": "Server produksi",
    "events": [
      "payment.succeeded",
      "payment.failed"
    ],
    "status": "active",
    "disabled_reason": "string",
    "consecutive_failures": 0,
    "secrets": [
      {
        "last4": "Xk3a",
        "status": "active",
        "retire_at": "2026-10-26T03:04:05.000Z"
      }
    ],
    "created_at": "2026-10-26T03:04:05.000Z",
    "secret": "whsec_k3f9…"
  },
  "meta": {
    "request_id": "req_Hy3k9QzT2LmN8vXa"
  }
}