---
name: webhook-execution-finished
description: >
  Instructs AI agents how to receive and handle Kyriba process template
  execution-finished webhook events. Kyriba POSTs a notification when a
  process template task completes (Complete, Warning, Error, or Cancelled).
version: 1.0.0
authors:
  - kyriba
tags:
  - kyriba
  - webhook
  - spi
  - process-templates
  - 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 - Execution Finished

>  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?

Kyriba fires this event when a process template task finishes execution. Use it to trigger downstream actions (e.g. start ERP processing) without polling the Process Templates API.

---

## Your server must

1. Expose `POST` on any path you configure in Kyriba (e.g. `/webhook`)
2. Validate the `kyriba-webhook-payload-signature` HMAC-SHA256 header
3. Return `202 Accepted`

---

## Inbound Payload

```json
{
  "webhookApiVersion": "v1",
  "eventId": "03737943-5976-46a5-8735-765b668103ae",
  "kyribaEntity": "process_template",
  "eventType": "execution_finished",
  "eventTime": "2023-03-23T06:52:10.134Z",
  "kyribaPlatform": { "baseUrl": "https://www.demo.kyriba.com" },
  "kyribaCustomer": { "code": "ACMECORP" },
  "kyribaUser": { "code": "JOHNSMITH", "uuid": "123e4567-..." },
  "eventDetails": {
    "executionFinished": {
      "processTemplate": { "uuid": "6c3a81f1-...", "code": "PT" },
      "taskUuid": "5efb37b2-e69c-45ea-a6c9-5c9e3ae6a0aa",
      "taskDetails": {
        "status": "Complete",
        "subTasks": []
      },
      "associatedFileImport": null
    }
  }
}
```

---

## Key Fields

| Field | Description |
|---|---|
| `eventId` | UUID - use for deduplication |
| `eventDetails.executionFinished.processTemplate.code` | Process template code |
| `eventDetails.executionFinished.processTemplate.uuid` | Process template UUID |
| `eventDetails.executionFinished.taskUuid` | Task UUID - same as `taskUuid` in Process Templates API |
| `eventDetails.executionFinished.taskDetails.status` | `Complete`, `Warning`, `Error`, or `Cancelled` |
| `eventDetails.executionFinished.taskDetails.subTasks[]` | Child task statuses (recursive) |
| `eventDetails.executionFinished.associatedFileImport` | `null` or `{ fileName, fileId }` if triggered by file import |

### `taskDetails.status` values

| Value | Meaning |
|---|---|
| `Complete` | Task finished successfully |
| `Warning` | Task finished with warnings |
| `Error` | Task failed |
| `Cancelled` | Task was cancelled |

>  Treat `status` as an open set - new values may be added.

---

## Critical Rules

1. Always return `202`
2. Use `eventId` for deduplication
3. `associatedFileImport` is `null` when the task was not triggered by a file upload
4. `taskUuid` matches the `taskUuid` returned by `POST /api/v1/process-templates/{code}/execute`

---

## OpenAPI Spec

- OpenAPI: `https://developer.kyriba.com/static/apis/webhook-execution-finished/process_template-execution_finished.yaml`