# Run hooks API

> Zoek de twee HTTP-endpoints op waarmee je een event-trigger afvuurt en het resultaat van een generic run leest, met authenticatie, bodies en statuscodes.

- Type: Naslag
- Voorwaarden: Een event-trigger met zijn URL en secret
- Gerelateerd: [Een event-trigger maken](https://platform.dxvagentic.com/docs/nl/developers/event-triggers.md), [Agents als API](https://platform.dxvagentic.com/docs/nl/developers/generic-agents.md)
- Laatst bijgewerkt: 2026-10-19
- URL: https://platform.dxvagentic.com/docs/nl/developers/run-hooks-api

Bij event-triggers horen twee publieke endpoints. Beide authenticeren met het secret van de trigger, niet met een sessie.

## Authenticatie

Stuur het secret als `Authorization: Bearer <secret>`. Een queryparameter `?token=<secret>` wordt ook geaccepteerd voor afzenders die alleen een kale URL kunnen instellen. Een header heeft de voorkeur, want querystrings komen in logs en proxies terecht.

## Een trigger afvuren

`POST /api/hooks/events/:uuid`

De `:uuid` is de identifier in de trigger-URL. De body is willekeurige JSON. Optioneel: een `X-DXV-Event-Key`-header (of `?key=`) die de controle op lopende runs en de afkoelperiode per sleutel afbakent. Een sleutel moet voldoen aan `^[A-Za-z0-9._:-]{1,100}$`.

| Status | Body                                              | Betekenis                                                             |
| ------ | ------------------------------------------------- | --------------------------------------------------------------------- |
| 202    | `{ "featureRequestId": 123, "dispatched": true }` | Er is een run aangemaakt. Komt terug voordat de agent heeft gedraaid. |
| 200    | `{ "skipped": "inactive" }`                       | De trigger is gepauzeerd.                                             |
| 200    | `{ "skipped": "in_flight" }`                      | Er is nog een run actief voor deze trigger (of sleutel).              |
| 200    | `{ "skipped": "cooldown" }`                       | De afkoelperiode is nog niet voorbij.                                 |
| 400    | `{ "message": "..." }`                            | De event-sleutel is niet geldig.                                      |
| 401    | `{ "message": "Invalid token" }`                  | Het secret ontbreekt of klopt niet.                                   |
| 404    | `{ "message": "Unknown event trigger" }`          | De UUID is geen bekende trigger.                                      |

Een overgeslagen antwoord bij een aflevering met sleutel geeft ook `key` terug.

### Over featureRequestId

`featureRequestId` is het id van de run die is aangemaakt. De naam is historisch: het platform slaat een run op als een verzoek. Gebruik deze waarde als `:id` in het endpoint hieronder.

## Een generic run lezen

`GET /api/hooks/runs/:id`

Gebruik hetzelfde secret. Alleen runs van generic agents die door die trigger zijn afgevuurd, kun je lezen.

| Status | Body                                                     | Betekenis                                                        |
| ------ | -------------------------------------------------------- | ---------------------------------------------------------------- |
| 200    | `{ "id", "status", "createdAt", "updatedAt", "result" }` | De run. `result` is `null` totdat de run een eindstatus bereikt. |
| 403    | `{ "message": "Access denied" }`                         | Het secret hoort niet bij de trigger van deze run.               |
| 404    | `{ "message": "Not found" }`                             | De run bestaat niet of is geen generic run.                      |

Poll dit endpoint totdat `result` niet `null` is, of kijk later opnieuw.