Skip to main content

Webhook Handlers

Webhook handlers give you public HTTPS endpoints that external systems — Stripe, GitHub, Shopify, your own services — can call when something happens. Each handler validates the incoming request, extracts variables from the payload, and executes a resource you choose: a tool, an agent, a manager, or a direct AutessaDB operation.

What it's for​

Agents and tools normally run when you (or your API) invoke them. Webhook handlers flip the direction: the outside world initiates. A payment processor reports a charge, a CRM announces a new lead, a CI pipeline finishes a build — the handler turns that HTTP call into an execution inside Autessa, with fields from the payload mapped into the resource's inputs. No client API key is involved; each webhook carries its own dedicated key.

Open API Management → Webhook Handlers in the sidebar. The page lists your handlers in a table — name, an Enabled/Disabled status badge, a View History button, and View Calling Instructions — with a Create Webhook button at the top. Click a row to open its configuration.

Key concepts​

  • One trigger URL per handler — every handler is called through the shared endpoint https://api.autessa.com/clients/custom-webhooks?resourceId={webhookId}, which accepts any HTTP method (GET, POST, PUT, DELETE, PATCH) so it fits whatever the sending system insists on. You don't configure allowed methods; the method used is simply recorded per delivery. See the Custom Webhooks API for the full request contract.
  • Dedicated webhook key — each handler gets its own wh:{keyId}:{keySecret} credential, shown once in the "Webhook Created Successfully" modal. Pass it in the Authorization header, or as an authorization query parameter when the sender can't set headers. Lost it? View Calling Instructions → Reset API Key issues a new one and immediately invalidates the old.
  • Four target types — the Resource Execution section selects what runs: a Tool (with argument mappings, environment variables, and private variables that are never logged), an Agent or Manager (with a user message and prompt template variables), or AutessaDB (a direct Insert or Update on a table, no agent involved).
  • Payload transformation — incoming requests are reduced to a flat set of variables, either with JSONPath mappings (orderId ← $.order.id) or an AutessaScript transform that receives the raw payload, headers, and queryParams and returns an object. Everywhere else in the form, @@{variableName} references substitute those variables into tool arguments, user messages, and column values.
  • Request validation — an optional AutessaScript that runs on every delivery after key authentication. It receives headers, body, and queryParams and must return true or false — use it to verify sender signatures (a Stripe or GitHub HMAC, for example). A false return rejects the delivery with 401.
  • Asynchronous execution — a valid delivery returns 202 Accepted with an executionId immediately; the resource runs in the background under the handler's Execution Settings (timeout, default 300 seconds; max retries, default 3; retry delay, default 5 seconds). The caller never receives the resource's output — you inspect it in execution history.

How to create a webhook handler​

  1. On the Webhook Handlers page, click Create Webhook.
  2. Under Basic Information, name the handler (e.g. "Stripe Payment Webhook"), add a description, and leave Enabled checked.
  3. Optionally enable Request Validation and write the signature-check script.
  4. Under Payload Transformation, map the payload fields you need — JSONPath pairs for straightforward JSON bodies, an AutessaScript transform for anything more involved. JSONPath mode requires at least one mapping.
  5. Under Resource Execution, pick the resource type and target, then wire the extracted variables into its inputs with @@{variableName} references.
  6. Adjust Execution Settings if the defaults don't fit, then click Create Webhook.
  7. The success modal shows the full trigger URL and the API key — copy the key now; this is the only time it's displayed. Confirm with I've Saved My API Key - Continue.
  8. Paste the trigger URL and key into the external system's webhook settings.

How to review deliveries​

  1. Click View History on the handler's row.
  2. The table lists each execution with its ID, status (QUEUED, SUCCESS, or FAILED), resource type, queued time, and duration.
  3. Click View on a row to open Execution Details: the HTTP method and source IP, the request headers and payload, the Transformed Variables your transform produced, and the Resource Response from the tool, agent, manager, or database operation.

There is no in-app "send test request" button — the way to test a handler is to call its trigger URL with curl (or the sender's test-delivery feature) and read the outcome in execution history.

Handlers can also be shared from the edit page (Share): keep private, share company-wide read-only, or company-wide editable. Only the owner can delete a handler, and disabled handlers reject all deliveries.

Sharing and access levels​

Every handler starts private to its owner. Share it with specific teammates — each at their own access level — or company-wide at a single level for everyone. What each level allows:

LevelWhat it lets a teammate do
READView the handler
WRITEEdit the handler
PUBLISHSame as WRITE — handlers have no publish step
ADMINShare the handler and regenerate its API key

Deleting a handler is owner-only — ADMIN is not enough. The owner always has ADMIN implicitly.