---
name: webhook-document-approved
description: >
  Instructs AI agents how to receive and handle Kyriba Working Capital
  document-approved webhook events. Kyriba POSTs a notification when one
  or more SCF documents are approved 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 Approved

>  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 **approved** in a single batch action. The payload contains the `actionId` and count - use the Documents API to retrieve the individual documents.

---

## 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_approved",
  "eventTime": "2023-03-23T06:52:10.134Z",
  "kyribaPlatform": { "baseUrl": "https://www.demo.kyriba.com" },
  "kyribaCustomer": { "code": "ACMECORP" },
  "kyribaUser": { "code": "JOHNSMITH", "uuid": "123e4567-..." },
  "eventDetails": {
    "documentsApproved": {
      "actionId": "A_ACMECORP_11115555_2023-29-03T06:52:134Z",
      "count": 3
    }
  }
}
```

---

## Key Fields

| Field | Description |
|---|---|
| `eventId` | UUID - use for deduplication |
| `kyribaCustomer.code` | Customer code - use to scope Documents API query |
| `eventDetails.documentsApproved.actionId` | Action identifier. Pattern: `A_<customerCode>_<timestamp>` |
| `eventDetails.documentsApproved.count` | Number of documents approved in this action |

### `actionId` pattern

- Approvals: `A_<kyribaCustomerCode>_<YYYY-DD-MMThh:mm:ssZ>`
- Cancellations: `C_<kyribaCustomerCode>_<YYYY-DD-MMThh:mm:ssZ>`

---

## After receiving - query the Documents API

The webhook does not include individual document details. Use the actionId to fetch them:

```
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) for full details.

---

## Critical Rules

1. Always return `202`
2. Use `eventId` for deduplication
3. `count` tells you how many documents were affected - query the Documents API for details
4. `kyribaEntity` is `supply_chain_finance_document` - both approved and cancelled events use the same entity

---

## OpenAPI Spec

- OpenAPI: `https://developer.kyriba.com/static/apis/webhook-document-approved/documents_approved.yaml`