Skip to main content
This guide takes you from zero to a working integration: an API key, a successful call, and a real webhook delivery you can inspect.
Every ID in this guide (aut_…, whk_…, evt_…, agt_…) is an opaque, prefixed string — never a UUID, and never something you parse or validate.

​
Prerequisites

  • An Agentova workspace where you’re an admin, with at least one active automation. There’s no separate test environment: if you’d rather not touch your real automations, use a workspace dedicated to testing (see below).
  • curl and jq in a terminal.
  • A browser, to open a webhook.site URL.

​
Get started

1

Create your API key

In Agentova, open Paramètres → API (Settings → API) and click Créer une clé (Create a key). The key looks like agk_live_ followed by 32 characters, and is shown only once. One key gives access to the entire workspace — there’s no per-key scoping in v1.Keep it in a variable for the rest of this guide:
Keep this key secret. Anyone with it can read your workspace’s leads and runs, and pause or activate its automations. See Security.
2

Make your first call

List the automations that are currently active:
A working key returns a paginated list:
An automation’s name says what it does, followed by the name of its agent.Pick an automation that isn’t business-critical — you’ll pause it for a few seconds — and keep its id:
A missing or revoked key returns 401 invalid_api_key instead — see Errors.
3

Open a receiver for your first webhook

Go to webhook.site and copy the unique URL it gives you. You’ll use it as the subscription target — no server of your own required for this guide.
4

Subscribe to an event

The response includes a secret — shown only once. It’s what you use to verify the X-Agentova-Signature header of every delivery to this subscription:
Keep the id too: you’ll need it to clean up.
5

Make the event happen

This pauses a real automation until you reactivate it. Run both commands back to back, on a non-critical automation: nothing that arrives during a pause is caught up afterwards — an email received while its automation is paused gets no reply (see Concepts).
Pause the automation you picked, then reactivate it:
Refresh the webhook.site page: two deliveries land, one per status change — usually within seconds — each with an X-Agentova-Signature header and a body like this one, where data is the whole automation:
The two deliveries can arrive in any order: to know the latest status, compare data.updated_at, not the order of arrival. To check a signature yourself, Webhooks & signatures has code in Node.js, Python and PHP, and a test vector.
6

Clean up

204 means the subscription is gone. If you created the key only for this guide, revoke it in Paramètres → API.

​
Testing without touching production

There’s no sandbox and no test key: every key is a live key on a real workspace. To experiment safely, create a workspace dedicated to development and testing in Agentova, with its own automations and its own key, and keep your production workspace for real traffic.

​
Explore without a workspace

To discover the API without an Agentova account, run a mock generated from the contract (the same file the API Reference tab is built from). It answers every route with its documented examples, but it doesn’t keep state, doesn’t send webhooks and doesn’t enforce rate limits.
Then use http://127.0.0.1:4010 instead of https://core-api.agentova.ai/v1 in the commands above.

​
Next steps

Concepts

What the API covers: automations, lead sources, runs.

Webhooks & signatures

Delivery, retries, and signature verification.

Errors

The full list of error codes and how to handle them.

Rate limits

Quotas, headers, and what happens past them.