View as Markdown Open in Claude Open in ChatGPT

Workflows

Dynamic processing of customer journeys and events.

Trigger workflow via webhook

POST/workflows/webhook/{path...}

Trigger a registered workflow via webhook. The wildcard path is matched against registered workflow webhook paths.

If at least one workflow is registered with the matching path, the request body is forwarded to the workflow(s) and a 200 response is returned.

If no workflows match the provided path, a 400 Bad Request is returned.

Path parameters

path...stringrequired

The wildcard webhook path to match against registered workflows. Leading slashes in the workflow registration are ignored, so support/intents/reward/topup and /support/intents/reward/topup are equivalent.

This is a greedy path parameter, meaning it captures the entire remainder of the URL path.

Headers

X-Idempotency-Keystringmax length 256

A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request.

Modified requests with the same idempotency keys are rejected with a 409 Conflict status code.

Bodyrequiredapplication/json

The webhook payload. Can be any valid JSON object. The payload data is passed to the matching workflow(s) which can access and use any properties from it.

propertyNameany

Any additional properties, passed through as given.

Responses

200

Webhook successfully delivered to at least one registered workflow.

application/json

Webhook successfully delivered to at least one registered workflow.

object

workflowTasksarray of EmbeddedWorkflowTaskrequired

List of workflow tasks that were triggered by this webhook.

Show child attributes

workflowTaskIdstringrequired

The unique identifier for the workflow task.

namestringrequired

The name of the workflow that was triggered.

descriptionstring

A description of what the workflow task does.

createdAtstringdate-timerequired

When the workflow task was created.

400

The request was malformed or invalid.

application/json

The request was malformed or invalid.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

401

Authentication is required to access this resource.

application/json

Authentication is required to access this resource.

objectError

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

internalCodestring

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

403

Access to this resource is forbidden.

application/json

Access to this resource is forbidden.

objectError

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

internalCodestring

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

409

The request conflicts with the current state of the resource.

application/json

The request conflicts with the current state of the resource.

objectError

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

internalCodestring

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

429

Too many requests have been sent in a given amount of time.

application/json

Too many requests have been sent in a given amount of time.

objectError

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

internalCodestring

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

500

An unexpected error occurred on the server.

application/json

An unexpected error occurred on the server.

objectError

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use internalCode.

internalCodestring

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

No auth required

POST /workflows/webhook/{path...}

curl https://apiv2.example.com/api/v2/workflows/webhook/support/intents/reward/topup \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{}'

fetch('https://apiv2.example.com/api/v2/workflows/webhook/support/intents/reward/topup', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({})
})

requests.post(
    "https://apiv2.example.com/api/v2/workflows/webhook/support/intents/reward/topup",
    headers={
      "Content-Type": "application/json"
    },
    json={}
)

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/workflows/webhook/support/intents/reward/topup"

	payload := strings.NewReader(`{}`)

	req, _ := http.NewRequest("POST", requestUrl, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

{
  "workflowTasks": [
    {
      "workflowTaskId": "f47ac10b-58cc-4372-a567-0e2b2c3d479",
      "name": "Reward customer with data top-up",
      "description": "Rewards a customer's subscription with the specified data top-up product offering.",
      "createdAt": "2024-01-15T10:35:00Z"
    }
  ]
}

{
  "message": "The request body is invalid.",
  "code": "bad_request",
  "details": [
    {
      "message": "Email format is invalid.",
      "code": "invalid_email",
      "property": "contact.email"
    }
  ],
  "hint": "Check the request payload and correct the highlighted fields."
}

{
  "message": "Authentication is required to access this resource.",
  "code": "unauthorized",
  "hint": "Provide a valid API key in the X-Api-Key header."
}

{
  "message": "You do not have permission to perform this action.",
  "code": "forbidden",
  "hint": "Ensure your API key or user has the required permissions."
}

{
  "message": "The request conflicts with the current state of the resource.",
  "code": "conflict",
  "hint": "Reload the resource to get its latest state before retrying."
}

{
  "message": "Too many requests. Please slow down.",
  "code": "too_many_requests",
  "hint": "Retry after the number of seconds indicated in the Retry-After header."
}

{
  "message": "An unexpected error occurred on the server.",
  "code": "internal_server_error",
  "hint": "Retry the request later. If the problem persists, contact support."
}