Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.apifycloud.io/llms.txt

Use this file to discover all available pages before exploring further.

Integrations let you forward widget events to any HTTP destination — your own server, an analytics platform, a CRM, a Slack channel — without writing any client-side code. Events are sent to our server using a keepalive request and dispatched from there to your integrations with retries and a circuit breaker — so they survive the visitor closing the page in most cases.

​
How it works

When the widget emits an event, ApifyCloud fans it out to each active integration configured on the app: 
Widget event
    │
    ▼
ApifyCloud runtime
    │
    ├──▶ Integration 1 (your analytics endpoint)
    ├──▶ Integration 2 (your team chat webhook)
    └──▶ Integration 3 (your CRM)
Each integration:
  • Has its own URL, headers, and authentication
  • Is filtered to the events you want
  • Retries on failure with exponential backoff and jitter
  • Trips a circuit breaker after sustained failures
  • Encrypts its secrets at rest

​
Creating an integration

In the console under Call Studio → Integrations:
1

Set the destination URL

HTTPS only. HTTP URLs are rejected to prevent plaintext leakage of PII.
2

Pick the events to forward

By default no events are selected. Choose specifically which ones you want delivered — most integrations only need a subset.
3

Add auth headers or secrets

Static headers (e.g. Authorization: Bearer ...) go in the headers list. Values stored under the Secrets section are encrypted at rest and can be referenced from URLs or headers.
You can have up to 3 active integrations per app. This cap is deliberate — more integrations means more latency on the shared dispatch loop. If you need more, contact support.

​
Request format

We POST a JSON body with the event envelope: 
{
  "name": "call_ended",
  "data": {
    "duration": 187,
    "reason": "user_hangup",
    "context": { "orderId": "A-12345" }
  },
  "timestamp": "2026-04-19T14:08:29.446Z",
  "app": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "My Support Line"
  }
}
The body is UTF-8 JSON with Content-Type: application/json.

​
Securing your endpoint

Add an Authorization: Bearer <token> header (or any other auth header you prefer) when creating the integration. Your endpoint rejects any request without the matching token.

​
Secrets

Secrets are values you don’t want to see again after saving — API keys, bearer tokens, signing keys. Store them in the Secrets section of the integration:
  • Values are encrypted at rest with AES-256-GCM.
  • Reveal is one-time-only, with a full audit log (who revealed what, when, from which IP).
  • Referenced in URLs and headers using the {secret.keyName} syntax.
  • Reveals are rate-limited (10 per hour per integration) to slow down an attacker with compromised console access.
Rotating a secret: edit the integration, find the secret in the list, replace its value, and save. The new value takes effect on the next delivery.

​
Delivery reliability

​
Timeouts

Each delivery has a configurable timeout, up to 10 seconds. If your endpoint doesn’t respond within the configured window, it counts as a failure.

​
Retries

On transient failure (5xx response, connection reset, timeout) we retry with exponential backoff and ±20 % jitter. After up to 3 attempts the delivery is marked failed.

​
Short-circuit on 4xx

Any 4xx response stops retries immediately. A 4xx means the request was rejected by your endpoint and retrying won’t fix it — fix the integration config or your endpoint.

​
Circuit breaker

After 20 consecutive failures across any events, the integration is automatically deactivated and stops dispatching. Fix the issue (wrong URL, expired token, endpoint down) and reactivate the integration from the console. This protects you from:
  • Burning retries against a dead endpoint
  • Accumulating a retry backlog that delivers out-of-order
  • Triggering rate limits on third-party services

​
Body size cap

Request bodies are capped at 64 KB. Events are well under this — it’s a defensive limit only.

​
Debugging a failing integration

The integration list shows a badge — Active or Paused — and a success-rate percentage. If the integration is Paused, the circuit breaker tripped and you need to reactivate it after fixing the cause. If the success rate is low, your endpoint is rejecting deliveries.
Did the request reach you? If yes, check the response status — that’s the value our dispatcher sees. If no, the issue is DNS or a firewall on your side.
If live events don’t arrive, check the event allowlist on the integration. It’s easy to enable it for call_started but forget call_ended.
See Request format above and compare against what your endpoint expects.

​
What’s next

Events

Catalogue of events you can subscribe to.

Security

How integration secrets and event data are protected.

Troubleshooting

When deliveries fail and you can’t tell why.