Webhooks

A Webhook lets AI Studio push data or events to an external HTTP receiver without continuous polling. This repository confirms two categories:

• Data export: Deliver processing results from the Catalog to an external system.

• Platform notifications: Send jobs, alerts, and other events currently exposed by the product to a notification channel or custom receiver.

A Webhook has the opposite direction from a REST data source. A REST data source reads a third-party endpoint into the Catalog; a Webhook sends from AI Studio.

Capture the actual contract first

Export tasks, event types, and deployment versions may use different payloads. Before implementing a receiver, obtain the following from the relevant configuration page:

Information	Used for
HTTP method and destination URL requirements	Routing the request
Headers and content type	Reading the body and identifying a version
Payload example and field descriptions	Parsing and validation
Signature, secret, or source restriction	Authenticating the sender
Successful response condition	Acknowledging delivery
Timeout, retry, and replay behavior	Idempotency and capacity planning

This repository does not yet define a common event envelope, signing algorithm, or retry count for every Webhook. Do not assume that a payload contains fields such as id, event, or timestamp, and do not infer a signing scheme from another product’s Webhook example.

Configure delivery

1. Create a dedicated HTTPS route in the receiving system and accept only the expected method and content type.

2. In the applicable AI Studio export, notification, or alert configuration, choose the Webhook option offered by the page.

3. Enter the receiver URL and any credential or secret requested by the page.

4. Use the page’s test action after saving. If no test action is available, trigger one low-risk task or event.

5. Compare the actual request headers, raw body, response, and duplicate-delivery behavior with the displayed contract.

6. Enable production events only after validation, then monitor delivery failures and processing backlog.

The event types, channels, and rules available on notification pages depend on the deployment. An event that is not displayed should not be treated as supported.

Receiver processing order

The following is a receiver design recommendation, not a promise about platform payload fields:

Read the raw request body
  → verify the source or signature exactly as documented
  → validate content type, size, and required fields
  → deduplicate by an event ID or business key, if supplied
  → persist work to a queue or database
  → return the documented success response
  → perform slow business processing asynchronously

Signature schemes commonly operate on the raw bytes, so do not reserialize JSON before verification. If the deployment does not provide signing, combine HTTPS with controls such as a dedicated high-entropy URL, gateway authentication, an IP allowlist, or network isolation, according to deployment capabilities and organizational policy.

Idempotency and retries

Only the actual configuration documentation can establish when AI Studio retries. A receiver should still assume that the same business message can arrive more than once:

• If the payload supplies a stable event identifier, enforce uniqueness on that identifier.

• Without an event identifier, choose a business key that cannot merge distinct events and use an appropriate deduplication window.

• Track “received” separately from “business processing complete.”

• Retry downstream work in the receiver’s queue instead of depending on another platform delivery.

• Log delivery time, event type when present, processing status, and a related request identifier without storing secrets or complete sensitive bodies.

Whether to return 2xx immediately after durable acceptance depends on the documented success condition and the application’s consistency requirements. Receiver processing must finish within the timeout displayed by the configuration page.

Exercise the receiver

First send a custom request to your own test route to verify routing, logs, and responses. This tests only the receiver; it does not simulate an official AI Studio payload:

curl --request POST "$WEBHOOK_TEST_URL" \
  --header "Content-Type: application/json" \
  --data '{"source":"local-test"}'

Then test again through AI Studio or a real low-risk event. The production parser should accept only the structure declared by the configuration page and observed in an actual request.

Change endpoints or rotate secrets

When changing a URL, payload version, or signing secret, allow old and new configurations to overlap when possible:

1. deploy a receiver that understands the new contract;

2. switch and verify the test environment;

3. switch production delivery;

4. revoke the old secret and route after confirming that no new traffic uses them.

If the page offers neither dual secrets nor version negotiation, do not assume zero-downtime rotation. Schedule a maintenance window or use a gateway for the transition.

Troubleshoot delivery

Symptom	Check
No request arrives	Whether the event or task actually occurred, URL reachability from the platform, DNS, and firewall
Repeated delivery	Success response requirements, receiver timeout, and failures before the response
Signature verification fails	Raw body usage, secret for the active configuration, clock, and encoding required by the actual algorithm
Payload parsing fails	Content type, event type, payload version, and optional-field handling
Test succeeds but production fails	Production payload size, concurrency, permissions, and downstream dependencies

For data-export boundaries, see Platform Capabilities. For notification-channel procedures, see Alerts and notifications.