---
name: webhook-document-cancelled
description: >
  Instructs AI agents how to receive and handle Kyriba Working Capital
  document-cancelled webhook events. Kyriba POSTs a notification when one
  or more SCF documents are cancelled in a batch action.
version: 1.0.0
authors:
  - kyriba
tags:
  - kyriba
  - webhook
  - spi
  - working-capital
  - api
---

> **Auth** — POST {AUTH_BASE_URL}/oauth/token · Basic base64(CLIENT_ID:CLIENT_SECRET) · no scope.
> Use token_type verbatim — do not hardcode `Bearer`. On 401: retry once with the other scheme (`token` vs `Bearer`). On 429: wait Kyriba-Customer-Rate-Limit-Reset.

# Kyriba API Skill: Webhook - Documents Cancelled

>  This is an **inbound webhook (SPI)** - Kyriba calls your server. You do not call Kyriba.

>  No OAuth scope needed. Authentication is via HMAC signature on the `kyriba-webhook-payload-signature` header.

---

## What is this webhook?

Fires when one or more Working Capital (Supply Chain Finance) documents are **cancelled** in a single batch action. Identical structure to `webhook-document-approved` - only `eventType` and the `eventDetails` key differ.

---

## Your server must

1. Expose `POST` on any path you configure in Kyriba
2. Validate the `kyriba-webhook-payload-signature` header
3. Return `202 Accepted`

---

## Inbound Payload

```json
{
  "webhookApiVersion": "v1",
  "eventId": "571cdd45-df97-401e-a354-a88f6db9532b",
  "kyribaEntity": "supply_chain_finance_document",
  "eventType": "documents_cancelled",
  "eventTime": "2023-03-23T06:52:10.134Z",
  "kyribaPlatform": { "baseUrl": "https://www.demo.kyriba.com" },
  "kyribaCustomer": { "code": "ACMECORP" },
  "kyribaUser": { "code": "JOHNSMITH", "uuid": "123e4567-..." },
  "eventDetails": {
    "documentsCancelled": {
      "actionId": "C_ACMECORP_11115555_2023-29-03T06:52:134Z",
      "count": 3
    }
  }
}
```

---

## Key Fields

| Field | Description |
|---|---|
| `eventId` | UUID - use for deduplication |
| `kyribaCustomer.code` | Customer code |
| `eventDetails.documentsCancelled.actionId` | Action identifier. Pattern: `C_<customerCode>_<timestamp>` |
| `eventDetails.documentsCancelled.count` | Number of documents cancelled in this action |

---

## Differences from webhook-document-approved

| | document-approved | document-cancelled |
|---|---|---|
| `eventType` | `documents_approved` | `documents_cancelled` |
| `eventDetails` key | `documentsApproved` | `documentsCancelled` |
| `actionId` prefix | `A_` | `C_` |

>  You can handle both events in a single endpoint - check `eventType` to route.

---

## After receiving - query the Documents API

```
GET /workcap/v2/documents?filter=actionId==<actionId>&offset=0&limit=100
```

See the [Documents Skill](https://developer.kyriba.com/static/llm/skills/documents/SKILL.md).

---

## Critical Rules

1. Always return `202`
2. Use `eventId` for deduplication
3. `eventDetails` key is `documentsCancelled` - not `documentsApproved`
4. `kyribaEntity` is `supply_chain_finance_document` (same as approved)

---

## OpenAPI Spec

- OpenAPI: `https://developer.kyriba.com/static/apis/webhook-document-cancelled/documents_cancelled.yaml`