Configure the org's outbound webhook

PUT

/v1/settings/webhook

curl --request PUT \
  --url https://dev-api.infiniteaudience.ai/v1/settings/webhook \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "url": "https://example.com", "secret": "example", "envelope_version": "legacy" }'

• Development API Server

Sets the org-level webhook URL and optional signing secret. When configured, the platform fires POST requests to this URL when async operations complete — audience builds (enrichment, propensity, similarity) and file delivery exports. Events fired: segment.ready, segment.failed, delivery.completed, delivery.failed. The signing secret is org-scoped and applies to all outbound dispatches, including per-request webhook_url overrides on individual API calls. Signed payloads include an X-CF-Signature: sha256= header (plus X-IA-Signature when envelope_version is “v1”). See the Webhooks tag for the full reference. secret and envelope_version are preserved from the existing configuration when omitted from the request body — this call is a merge, not a whole-object replace. Requires ‘account’ scope.

Authorizations

• bearerAuth

Request Body^required

Media typeapplication/json

object

url

required

HTTPS endpoint URL to receive webhook POST requests.

string format: uri

secret

HMAC-SHA256 signing secret. When set, every outbound webhook dispatch (org-configured and ad-hoc per-request) includes X-CF-Signature: sha256=. Verify with HMAC-SHA256(secret, raw-request-body) using timing-safe comparison. Omit to keep the existing secret unchanged.

string

>= 8 characters

envelope_version

Omit to keep the existing value unchanged (defaults to “legacy” for an org that has never set it).

string

Allowed values: legacy v1

Responses

200

Webhook configured.

Media typeapplication/json

object

ok

required

boolean

Example

{
  "ok": true
}

400

Invalid request — malformed body, missing required attribute, or failed validation. See error and message for details.

Media typeapplication/json

object

error

required

Stable machine-readable error code (e.g. INVALID_STATUS_TRANSITION, BILLING_INSUFFICIENT_BALANCE). Always present.

string

message

Human-readable explanation of the error.

string

code

Alternate machine-readable code — present on some endpoints as an alias for error for backward compatibility.

string

request_id

Opaque support/debug identifier when available.

string

key

additional properties

any

Examples

Examplevalidation_error

{
  "error": "Bad Request",
  "code": "MISSING_SEGMENTS",
  "message": "segment_ids is required for filter audiences."
}

401

Missing or invalid Bearer token. Obtain one via POST /v1/auth/token. When a token was supplied but rejected, code distinguishes TOKEN_EXPIRED (the token’s lifetime has passed — request a new one via POST /v1/auth/token and retry) from TOKEN_INVALID (malformed or revoked — re-authenticate).

Media typeapplication/json

object

error

required

Stable machine-readable error code (e.g. INVALID_STATUS_TRANSITION, BILLING_INSUFFICIENT_BALANCE). Always present.

string

message

Human-readable explanation of the error.

string

code

Alternate machine-readable code — present on some endpoints as an alias for error for backward compatibility.

string

request_id

Opaque support/debug identifier when available.

string

key

additional properties

any

Examples

{
  "error": "Unauthorized: Missing or invalid Authorization header"
}

{
  "error": "Unauthorized",
  "code": "TOKEN_EXPIRED",
  "message": "Your session has expired. Please sign in again."
}

403

Token is valid but lacks the required scope for this endpoint. Check the endpoint description for the required scope (discovery, purchase, or account).

Media typeapplication/json

object

error

required

Stable machine-readable error code (e.g. INVALID_STATUS_TRANSITION, BILLING_INSUFFICIENT_BALANCE). Always present.

string

message

Human-readable explanation of the error.

string

code

Alternate machine-readable code — present on some endpoints as an alias for error for backward compatibility.

string

request_id

Opaque support/debug identifier when available.

string

key

additional properties

any

Examples

Examplemissing_scope

{
  "error": "SCOPE_REQUIRED",
  "message": "This endpoint requires the purchase scope."
}