Skip to content
Infinite Audience Docs

Create a webhook-trigger subscription

POST
/v1/webhook-subscriptions
curl --request POST \
  --url https://dev-api.infiniteaudience.ai/v1/webhook-subscriptions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "target_url": "https://example.com", "events": [ "segment.ready" ] }'

Registers a durable trigger subscription — delivery is retried with exponential backoff and dead-lettered after repeated failures (a 410 response from target_url dead-letters immediately and revokes the subscription — this is how Zapier signals “this Zap was turned off”). Requires ‘account’ scope, or an OAuth access token — in the OAuth case, this subscription is bound to your connection automatically. Capped at 25 active subscriptions per org.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
target_url
required

Must be HTTPS and resolve to a public, non-internal address — validated at creation and re-validated before every delivery attempt.

string format: uri
events
required
Array<string>
>= 1 items
Allowed values: segment.ready segment.failed delivery.completed delivery.failed

Responses

Section titled “Responses”

201

Section titled “201”

Subscription created.

Media typeapplication/json

Response to POST /v1/webhook-subscriptions. secret is returned exactly once, in plaintext — it is never retrievable again after this response.

object
id
required
string
target_url
required
string format: uri
events
required
Array<string>
Allowed values: segment.ready segment.failed delivery.completed delivery.failed
secret
required

Plaintext HMAC-SHA256 signing secret. Store it now — every subsequent read only returns it masked.

string
status
required
string
Allowed values: active
created_at
required
string format: date-time
Example
{
  "events": [
    "segment.ready"
  ],
  "status": "active"
}

400

Section titled “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

Section titled “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"
}

403

Section titled “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."
}

409

Section titled “409”

The org already has 25 active subscriptions.

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
Examplegenerated
{
  "error": "example",
  "message": "example",
  "code": "example",
  "request_id": "example"
}