Ontwikkelaars
Bouw op VEPRA
Elke handeling van een persoon in de app is een opdracht met een naam, een schema en een recht. Dezelfde opdrachten worden aangeroepen met een API-sleutel, vanuit webhooks en door de agent. Er is geen tweede API.
API-sleutels
Een sleutel is een "service"-actor van het bedrijf met de rechten die u kiest bij het aanmaken (alleen uit uw eigen rechten, nooit members.manage). Maak hem aan onder Bedrijf → Agent en API-sleutels; het token verschijnt één keer en alleen de hash wordt opgeslagen.
Een sleutel bereikt alleen het eigen bedrijf (elke andere route antwoordt 403), verloopt wanneer u dat bepaalt en wordt met één klik ingetrokken. Hij heeft geen MFA: opdrachten die een verse code vereisen worden altijd geweigerd.
Een opdracht aanroepen
curl -X POST https://vepra.ai/v1/businesses/<BIZNESI>/commands/contact.save \
-H "Authorization: Bearer vak_..." \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"displayName":"Arta Leka","kind":"person","email":"[email protected]","phone":"+355691234567"}'De ontvangstbevestiging
{
"operationId": "3f1c...", "command": "contact.save", "status": "applied",
"resources": [{ "type": "Contact", "id": "a51d...", "version": 1 }],
"eventIds": ["..."], "correlationId": "...", "warnings": []
}Statussen: applied, awaiting_approval (goedkeuring binnen het platform), pending_external (wacht op een externe partij). Fouten: 401 onbekende of verlopen sleutel, 403 buiten de rechten of het bedrijf, 409 verouderde versie (expectedVersion), 422 ongeldige invoer met fieldErrors.
Idempotency-Key: dezelfde waarde twee keer geeft dezelfde ontvangstbevestiging zonder de handeling te herhalen.
Opdrachten
De volledige lijst met invoerschema’s staat in het OpenAPI-document: /v1/openapi.json (opdrachtroute: POST /v1/businesses/{businessId}/commands/{name}). Schema’s heten Input_<opdracht met underscores>, bijv. Input_contact_save.
Meest gebruikt: contact.save, lead.save, booking.hold / booking.confirm, quote.draft / quote.send, task.create, work.create, consent.record.
Lezen gebruikt dezelfde GET-routes als de app, bijv. GET /v1/businesses/{businessId}/contacts?limit=50, met het bijbehorende .read-recht.
Inkomende webhooks
Een openbaar adres waarnaar uw systemen (formulieren, betalingen, Activepieces, n8n, Zapier) POST'en. Maak het aan op dezelfde pagina: een naam, wat het doet (alleen workflows starten, of een opdracht met sjabloon uitvoeren) en het geheim, eenmaal getoond.
De afzender bewijst het geheim met X-Vepra-Signature: sha256=<HMAC-SHA256 van de body> of, als hij niet kan ondertekenen, met X-Vepra-Token: <geheim>. Geen bewijs: 401. Onbekend of uitgeschakeld adres: 404. Geweigerde aanroepen worden nooit vastgelegd.
Een aanroep met het token
curl -X POST https://vepra.ai/v1/hooks/<HOOK_ID> \
-H "X-Vepra-Token: vhk_..." \
-H "Content-Type: application/json" \
-d '{"name":"Arta Leka","email":"[email protected]","phone":"+355691234567"}'Ondertekenen (Node.js)
import { createHmac } from 'node:crypto';
const signature = 'sha256=' + createHmac('sha256', secret).update(rawBody, 'utf8').digest('hex');
// -> header X-Vepra-Signature: sha256=...Het opdrachtsjabloon
{ "displayName": "{{name}}", "kind": "person", "email": "{{email}}", "phone": "{{phone}}", "notes": "Nga {{source}}" }{{field.subfield}} haalt zijn waarde uit de body van de aanroep; een hele waarde behoudt zijn type (getal, lijst), een ontbrekende waarde laat het veld vallen. Elke aanroep geeft WebhookReceived, een workflowtrigger, met contactId wanneer de opdracht een contact opleverde.
Uitgaande webhooks
Vepra stuurt de gebeurtenissen van uw bedrijf naar een openbaar https-adres dat u opgeeft: contact opgeslagen, lead, reservering bevestigd, offerte geaccepteerd, opdracht aangemaakt… (alle, of alleen die u kiest). Privéadressen (10.x, 192.168.x, localhost) worden geweigerd.
Elke aanroep is een JSON-POST met drie headers: X-Vepra-Event, X-Vepra-Delivery en X-Vepra-Signature (sha256=HMAC-SHA256 van de body met het geheim dat u eenmaal kreeg). Antwoord 2xx binnen 10 seconden; omleidingen worden niet gevolgd.
Nieuwe pogingen na 1 min, 5 min, 30 min, 2 u en 12 u; na 5 pogingen wordt de aanroep opgegeven, na 20 opeenvolgende mislukkingen wordt het adres uitgeschakeld (schakel het opnieuw in vanaf de pagina). "Test" stuurt een HookTest.
De body van de aanroep
{
"id": "d3b7...", // X-Vepra-Delivery
"event": "ContactSaved", // X-Vepra-Event
"occurredAt": "2026-09-17T18:40:00.000Z",
"business": "58a7...",
"aggregate": { "type": "Contact", "id": "a51d...", "version": 3 },
"payload": { "...": "..." },
"attempt": 1
}Verificatie (Node.js)
import { createHmac, timingSafeEqual } from 'node:crypto';
export function verifyVepra(rawBody, signatureHeader, secret) {
const expected = 'sha256=' + createHmac('sha256', secret).update(rawBody, 'utf8').digest('hex');
const a = Buffer.from(signatureHeader ?? ''), b = Buffer.from(expected);
return a.length === b.length && timingSafeEqual(a, b);
}Verificatie (PHP)
$expected = 'sha256=' . hash_hmac('sha256', $rawBody, $secret);
$ok = hash_equals($expected, $_SERVER['HTTP_X_VEPRA_SIGNATURE'] ?? '');
De agent
De agent neemt een doel in gewone woorden en bouwt de aanroepen zelf: zijn hulpmiddelen zijn precies de contractopdrachten binnen de rechten van de actor. Facturen, betalingen, salarissen, licenties, perioden en lidmaatschappen worden nooit door de agent uitgevoerd; ze blijven voorstellen die een persoon uitvoert.
Geplande runs voeren een doel uit volgens een ritme (elk uur, dagelijks, op werkdagen, wekelijks) als eigen actor, laten een taak achter in Taken en melden het aan de maker. Een model met tool-use dat onder API-koppelingen is gekoppeld, is vereist.
Workflows
De stap "Opdracht aanroepen" van een workflow loopt ook door de pijplijn, als de "Workflow"-actor van het bedrijf, met getypeerde parameters (het label van het contact, de reserveringshandeling, het gesprekskanaal…). Gebeurtenissen die die actor veroorzaakt, starten nooit andere workflows, dus er zijn geen eindeloze ketens. De trigger WebhookReceived verbindt externe systemen met workflows.
Beveiliging
Tokens nooit in URL’s; sleutels worden gehasht opgeslagen, geheimen verzegeld. Elke aanroep wordt geaudit met de service-actor die hem deed. Grenzen: tot 10 sleutels, 10 schema’s, 20 inkomende webhooks en 10 uitgaande adressen per bedrijf; inkomende body tot 1 MB. De ratelimiet van de API geldt ook voor sleutels.
Vragen of een hogere limiet: [email protected].