POST/api/v2/webhooks

Add a webhook

At most 5 webhooks per business. The response contains secret only once (it can be viewed again in Settings › API & Webhook (Pengaturan › API & Webhook)). Use that secret to check the Klikflow-Signature header.

Send an Idempotency-Key header (for example a new UUID per request). A repeat with the same key within 24 hours gets the first answer again, so nothing is sent twice.

Key: kf_live_ / kf_test_… in the Authorization: Bearer header. Created in Settings › API & Webhook › Create key (Pengaturan › API & Webhook › Buat kunci).
Key scope: webhooks:manage
Plan feature: WhatsApp sending API

Body (JSON)

urlstringrequired
Public HTTPS URL, at most 500 characters.
eventsarray: message.received | message.status | contact.created | lead.created | order.paid | ticket.created | ticket.status | template.status | channel.statusrequired
Events to send; see the Webhook events guide.
descriptionstring
Description, at most 120 characters.

Possible errors

400 invalid_json Body is not valid JSON
400 idempotency_key_invalid Invalid Idempotency-Key
401 missing_key API key not sent
401 key_invalid Unknown API key
401 key_revoked API key revoked
401 key_expired API key expired
401 member_inactive Key creator is no longer a member
403 ip_not_allowed Server IP not in the key's list
403 plan_no_api Plan does not include the API for live keys
403 tenant_blocked Business access suspended
403 scope_missing Key lacks this permission
403 permission_missing Key creator's role lacks this permission
403 live_key_required Live key required
409 idempotency_conflict Idempotency-Key used for different content
409 request_in_progress The same request is still being processed
422 invalid_request Invalid field
422 webhook_limit Webhook limit reached
429 rate_limited Too many requests per minute
500 internal_error Problem at Klik Flow

Try it

This endpoint needs a live key, so it cannot be tried from the docs. Call it from your server.

Request example

curl -X POST "https://klikflow.id/api/v2/webhooks" \
  -H "Authorization: Bearer KUNCI_API" \
  -H "Idempotency-Key: 6f1c2a8e-4b1d-4c3a-9e2f-1a2b3c4d5e6f" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://toko-anda.id/klikflow/webhook","events":["message.received","message.status","order.paid"],"description":"Server toko"}'

Response example 201

{
  "data": {
    "id": 6,
    "object": "webhook",
    "url": "https://toko-anda.id/klikflow/webhook",
    "description": "Server toko",
    "events": [
      "message.received",
      "message.status",
      "order.paid"
    ],
    "status": "active",
    "paused_reason": null,
    "health": "Belum ada kiriman 7 hari",
    "failed_count": 0,
    "created_at": "2026-11-01T02:00:00.000Z",
    "last_success_at": null,
    "last_failure_at": null,
    "secret": "whsec_4Hf2Kp9Lq7Rt1Zs8Vb3Nm6Xc0Ya5Wd2E"
  }
}

Body (JSON)

Possible errors

Try it

Send WhatsApp from your system with the Klik Flow API.