Search docs

    Get the app
    View Markdown

    Webhooks

    Signed event delivery (Standard Webhooks).

    Generated from the contract, version 2.0.0-draft.2 (OpenAPI). Base URL https://usekabu.com/api. Errors are problem details, each code with its own page.

    Register an endpoint

    POST/v2/webhook_endpoints
    • Auth: an API key, or a signed-in human’s token (the Kabu apps).
    • Scopes: webhooks:write.
    • Signed-in humans: admin.
    Parameter In Type Required Description
    Idempotency-Key header string, at most 255 characters Optional Retry-safe key. For messages, sessions and responses it binds to the created object for its life; elsewhere for 24 h.
    Kabu-Org header string Optional Select a live membership (default personal org); non-member is 404. Human tokens are live-only. Caller user id is distinct from billing owner.

    Request body: WebhookEndpointCreate.

    Status Means Body
    201 OK WebhookEndpointWithSecret
    4XX Error Problem
    5XX Error Problem 
    curl -X POST "https://usekabu.com/api/v2/webhook_endpoints" \
  -H "Authorization: Bearer $KABU_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"url":"…","events":["…"]}'

    List endpoints

    GET/v2/webhook_endpoints
    • Auth: an API key, or a signed-in human’s token (the Kabu apps).
    • Scopes: webhooks:write.
    • Signed-in humans: admin.
    Parameter In Type Required Description
    limit query integer, from 1 to 100 Optional
    after query string Optional Opaque cursor from next_cursor.
    Kabu-Org header string Optional Select a live membership (default personal org); non-member is 404. Human tokens are live-only. Caller user id is distinct from billing owner.
    Status Means Body
    200 OK WebhookEndpointList
    4XX Error Problem
    5XX Error Problem 
    curl "https://usekabu.com/api/v2/webhook_endpoints" \
  -H "Authorization: Bearer $KABU_API_KEY"

    Get an endpoint

    GET/v2/webhook_endpoints/{endpoint_id}
    • Auth: an API key, or a signed-in human’s token (the Kabu apps).
    • Scopes: webhooks:write.
    • Signed-in humans: admin.
    Parameter In Type Required Description
    endpoint_id path string Required A whe_… id.
    Kabu-Org header string Optional Select a live membership (default personal org); non-member is 404. Human tokens are live-only. Caller user id is distinct from billing owner.
    Status Means Body
    200 OK WebhookEndpoint
    4XX Error Problem
    5XX Error Problem 
    curl "https://usekabu.com/api/v2/webhook_endpoints/$ENDPOINT_ID" \
  -H "Authorization: Bearer $KABU_API_KEY"

    Update an endpoint

    PATCH/v2/webhook_endpoints/{endpoint_id}
    • Auth: an API key, or a signed-in human’s token (the Kabu apps).
    • Scopes: webhooks:write.
    • Signed-in humans: admin.
    Parameter In Type Required Description
    endpoint_id path string Required A whe_… id.
    Kabu-Org header string Optional Select a live membership (default personal org); non-member is 404. Human tokens are live-only. Caller user id is distinct from billing owner.

    Request body: WebhookEndpointUpdate.

    Status Means Body
    200 OK WebhookEndpoint
    4XX Error Problem
    5XX Error Problem 
    curl -X PATCH "https://usekabu.com/api/v2/webhook_endpoints/$ENDPOINT_ID" \
  -H "Authorization: Bearer $KABU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

    Delete an endpoint

    DELETE/v2/webhook_endpoints/{endpoint_id}
    • Auth: an API key, or a signed-in human’s token (the Kabu apps).
    • Scopes: webhooks:write.
    • Signed-in humans: admin.
    Parameter In Type Required Description
    endpoint_id path string Required A whe_… id.
    Kabu-Org header string Optional Select a live membership (default personal org); non-member is 404. Human tokens are live-only. Caller user id is distinct from billing owner.
    Status Means Body
    204 Done
    4XX Error Problem
    5XX Error Problem 
    curl -X DELETE "https://usekabu.com/api/v2/webhook_endpoints/$ENDPOINT_ID" \
  -H "Authorization: Bearer $KABU_API_KEY"

    Rotate the signing secret (old one valid for 24 h)

    POST/v2/webhook_endpoints/{endpoint_id}/rotate_secret
    • Auth: an API key, or a signed-in human’s token (the Kabu apps).
    • Scopes: webhooks:write.
    • Signed-in humans: admin.
    Parameter In Type Required Description
    endpoint_id path string Required A whe_… id.
    Idempotency-Key header string, at most 255 characters Optional Retry-safe key. For messages, sessions and responses it binds to the created object for its life; elsewhere for 24 h.
    Kabu-Org header string Optional Select a live membership (default personal org); non-member is 404. Human tokens are live-only. Caller user id is distinct from billing owner.
    Status Means Body
    200 OK WebhookEndpointWithSecret
    4XX Error Problem
    5XX Error Problem 
    curl -X POST "https://usekabu.com/api/v2/webhook_endpoints/$ENDPOINT_ID/rotate_secret" \
  -H "Authorization: Bearer $KABU_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

    Send a signed ping now

    POST/v2/webhook_endpoints/{endpoint_id}/test
    • Auth: an API key, or a signed-in human’s token (the Kabu apps).
    • Scopes: webhooks:write.
    • Signed-in humans: admin.
    Parameter In Type Required Description
    endpoint_id path string Required A whe_… id.
    Idempotency-Key header string, at most 255 characters Optional Retry-safe key. For messages, sessions and responses it binds to the created object for its life; elsewhere for 24 h.
    Kabu-Org header string Optional Select a live membership (default personal org); non-member is 404. Human tokens are live-only. Caller user id is distinct from billing owner.
    Status Means Body
    200 OK WebhookAttempt
    4XX Error Problem
    5XX Error Problem 
    curl -X POST "https://usekabu.com/api/v2/webhook_endpoints/$ENDPOINT_ID/test" \
  -H "Authorization: Bearer $KABU_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

    Delivery attempts

    GET/v2/webhook_endpoints/{endpoint_id}/attempts
    • Auth: an API key, or a signed-in human’s token (the Kabu apps).
    • Scopes: webhooks:write.
    • Signed-in humans: admin.
    Parameter In Type Required Description
    endpoint_id path string Required A whe_… id.
    limit query integer, from 1 to 100 Optional
    after query string Optional Opaque cursor from next_cursor.
    Kabu-Org header string Optional Select a live membership (default personal org); non-member is 404. Human tokens are live-only. Caller user id is distinct from billing owner.
    Status Means Body
    200 OK WebhookAttemptList
    4XX Error Problem
    5XX Error Problem 
    curl "https://usekabu.com/api/v2/webhook_endpoints/$ENDPOINT_ID/attempts" \
  -H "Authorization: Bearer $KABU_API_KEY"

    Redeliver events after a checkpoint (bounded job)

    POST/v2/webhook_endpoints/{endpoint_id}/replay

    until defaults to the checkpoint current when the job is created. At most 7 days and 100,000 events per job, one running job per endpoint, delivered at the endpoint’s normal rate.

    • Auth: an API key, or a signed-in human’s token (the Kabu apps).
    • Scopes: webhooks:write.
    • Signed-in humans: admin.
    Parameter In Type Required Description
    endpoint_id path string Required A whe_… id.
    Idempotency-Key header string, at most 255 characters Optional Retry-safe key. For messages, sessions and responses it binds to the created object for its life; elsewhere for 24 h.
    Kabu-Org header string Optional Select a live membership (default personal org); non-member is 404. Human tokens are live-only. Caller user id is distinct from billing owner.

    Request body: WebhookReplay.

    Status Means Body
    202 OK Job
    4XX Error Problem
    5XX Error Problem 
    curl -X POST "https://usekabu.com/api/v2/webhook_endpoints/$ENDPOINT_ID/replay" \
  -H "Authorization: Bearer $KABU_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"after":"…"}'

    Webhook: An Event, signed per Standard Webhooks

    POSTyour endpoint (event)

    Kabu sends POST to each of your webhook endpoints, signed per Standard Webhooks: see Webhooks to verify it.

    Parameter In Type Required Description
    webhook-id header string Required
    webhook-timestamp header string Required
    webhook-signature header string Required

    Request body: Event.

    Status Means Body
    2XX Accepted. Anything else is retried with backoff for 3 days.

    Schemas

    WebhookEndpointCreate

    Property Type Required Description
    url string (uri) Required Public HTTPS only; the resolved address is re-checked on every attempt.
    events array of string, at least 1 items Required Event types, or [“*”].
    description string, at most 200 characters Optional
    api_version string, matching ^\d{4}-\d{2}-\d{2}$ Optional

    Unknown properties are refused.

    WebhookEndpointWithSecret

    Type: WebhookEndpoint and object.

    WebhookEndpoint

    Property Type Required Description
    object "webhook_endpoint" Required
    id string Required
    url string Required
    events array of string Required
    status string Required enabled, disabled or failing (open).
    api_version string Required
    description string or null Required
    created_at Timestamp Required

    WebhookEndpointList

    Property Type Required Description
    object "list" Required
    data array of WebhookEndpoint Required
    has_more boolean Required
    next_cursor string or null Required

    WebhookEndpointUpdate

    Property Type Required Description
    url string (uri) Optional
    events array of string Optional
    description string, at most 200 characters Optional
    enabled boolean Optional

    Unknown properties are refused.

    WebhookAttempt

    Property Type Required Description
    id string Required
    event string Required
    checkpoint string Optional Opaque events checkpoint at this attempt’s event, for choosing a console replay boundary. Never derive it from event id or time. Optional for older attempt records; existing exclusive after semantics are unchanged.
    status_code integer or null Required
    latency_ms integer or null Required
    ok boolean Required
    error string or null Required
    at Timestamp Required

    WebhookAttemptList

    Property Type Required Description
    object "list" Required
    data array of WebhookAttempt Required
    has_more boolean Required
    next_cursor string or null Required

    WebhookReplay

    Property Type Required Description
    after string Required
    until string Optional A checkpoint. Default: now.

    Unknown properties are refused.

    Job

    Property Type Required Description
    object "job" Required
    id string Required
    status string Required
    created_at Timestamp Required