Webhooks

Agents can be triggered via webhooks, allowing external systems to invoke agent pipelines through HTTP POST requests without API key authentication.

In the UI

Enabling Webhooks

1. Open the agent’s detail page
2. Click the Webhooks tab
3. Toggle Enable Webhook
4. Copy the generated webhook URL
5. Optionally configure authentication (Bearer token or HMAC signature)

Viewing Webhook Executions

1. Open the agent’s detail page
2. Click the Executions tab
3. Filter by Trigger: webhook to see only webhook-initiated runs

Via the API

Enable Webhooks

curl -X PATCH /agents/{id} \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "webhookEnabled": true
  }'

When enabled, the agent receives a unique webhook URL:

https://api.almyty.com/agents/{id}/webhook

Trigger via Webhook

Send a POST request to the webhook URL with the agent’s expected input:

curl -X POST /agents/{id}/webhook \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Process this incoming data",
    "payload": { "key": "value" }
  }'

Webhook invocations return immediately with an execution ID:

{
  "success": true,
  "data": {
    "executionId": "exec-uuid",
    "status": "running"
  }
}

Poll the execution endpoint for the result:

curl /agents/{id}/executions/{executionId} \
  -H "Authorization: Bearer $TOKEN"

Authentication

Webhooks support two authentication methods:

Bearer Token

Include the agent’s webhook secret in the Authorization header:

curl -X POST /agents/{id}/webhook \
  -H "Authorization: Bearer {webhook-secret}" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Hello" }'

HMAC Signature

For integrations that support webhook signatures (GitHub, Stripe, etc.), configure HMAC verification:

SIGNATURE=$(echo -n '{"message":"Hello"}' | \
  openssl dgst -sha256 -hmac "$SECRET" | cut -d' ' -f2)
 
curl -X POST /agents/{id}/webhook \
  -H "X-Webhook-Signature: sha256=$SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{"message":"Hello"}'

Use Cases

Rate Limits

Webhook endpoints are rate-limited to 100 requests per minute with a maximum of 10 concurrent executions. Requests exceeding the limit receive a 429 Too Many Requests response with a Retry-After header.