JSON Endpoint Connector

Overview

Inbound webhook endpoint that accepts authenticated JSON POST requests and parses the body, headers, URL suffix, and query-string into structured trigger output for use in a runbook. Pairs with the outbound HTTP connector.

Prerequisites

• A Xurrent iPaaS trigger URL. The platform generates one when you install this trigger in a runbook and shows it in the install view.
• API key, HTTP Basic Auth, or OAuth 2.0 client-credentials credentials for the caller. Populate whichever method the calling system supports. You can configure any combination on the same connection. Leave a method blank to disable it.
• For OAuth 2.0: the token URL to exchange credentials for a bearer token. The platform shows it in the install view after you save the connection.
• A caller system able to send JSON POST requests to the trigger URL over HTTPS.

Authentication

Every inbound request must authenticate with API key, Basic Auth, or OAuth 2.0 client credentials. Populate whichever method the calling system supports. You can configure any combination on one connection; the validator skips any method you leave blank.

API key

Field	Type	Required	Default	Description
key	String	Yes	-	Header or query-parameter name the caller sends the API key in (e.g. X-API-Key)
value	String	Yes	-	Expected API-key value
placement	Enum	No	Header	Where the caller places the key. Either Header or Query params

Basic auth

Field	Type	Required	Description
username	String	Yes	Expected Basic Auth username
password	Secret	Yes	Expected Basic Auth password. The caller sends it as Authorization: Basic <base64(user:pass)> per RFC 7617

OAuth 2.0 client credentials

Field	Type	Required	Default	Description
client_id	String	Yes	-	Client identifier issued to the caller
client_secret	Secret	Yes	-	Client secret paired with client_id. Stored as a non-reversible credential.
token_ttl_seconds	Integer	No	Server default	Lifetime of an issued bearer token, in seconds (60–86400).

The caller exchanges its client_id and client_secret at the token URL — shown in the install view after you save the connection — for a short-lived bearer token (per RFC 6749 §4.4). It then sends that token on each request as Authorization: Bearer <token>. Tokens are self-contained JWTs verified per RFC 9068. Configure this method only when the calling system supports the OAuth 2.0 client-credentials grant; leave it blank otherwise and the validator skips it.

Triggers

JSON Endpoint

Exposes a single HTTPS POST endpoint that the caller invokes with a JSON body. The trigger parses the body against the configured body_schema, extracts any declared headers, reads an optional trailing path segment as url_postfix, captures any query-string parameters, and emits a structured payload to the runbook.

Use case: receive webhook callbacks from any system that can POST JSON with an API key, Basic Auth, or an OAuth 2.0 bearer token. Common callers include monitoring tools, ITSM platforms, and custom integrations with no dedicated connector.

Input Parameters

Parameter	Type	Required	Default	Description
headers	Array of {name, array, required}	No	[]	Headers to extract from the incoming request. See headers[] fields below.
body_schema	SchemaField[]	Yes	-	Field-by-field definition of the JSON body the endpoint expects. Defines the shape of the body output.

headers[] fields

Field	Type	Required	Default	Description
name	String	Yes	-	Exact header name the caller will send. Pattern [A-Za-z0-9_-]+.
array	Boolean	No	false	When true, the incoming header value is split on ,\s+ into an array.
required	Boolean	No	false	When true, requests that omit this header are rejected.

Example Input

Trigger configuration (set once by the runbook author):

{
  "headers": [
    { "name": "X-Request-Id", "array": false, "required": true },
    { "name": "X-Tags", "array": true, "required": false }
  ],
  "body_schema": [
    { "id": "event_type", "label": "Event type", "type": "string", "required": true },
    {
      "id": "data",
      "label": "Data",
      "type": "nested",
      "required": false,
      "fields": [
        { "id": "source", "label": "Source", "type": "string", "required": false },
        { "id": "message", "label": "Message", "type": "string", "required": false }
      ]
    }
  ]
}

Sample incoming request, API key variant:

curl -X POST 'https://<your-ipaas-host>/inbound/<account_id>/<solution_uuid>/<runbook_uuid>/customer_42?region=eu' \
  -H 'X-API-Key: <api-key-value>' \
  -H 'X-Request-Id: 8b4e1c2f' \
  -H 'X-Tags: priority, followup' \
  -H 'Content-Type: application/json' \
  -d '{
    "event_type": "alert.created",
    "data": {
      "source": "external-system",
      "message": "threshold exceeded"
    }
  }'

Sample incoming request, Basic Auth variant:

curl -X POST 'https://<your-ipaas-host>/inbound/<account_id>/<solution_uuid>/<runbook_uuid>' \
  -u '<username>:<password>' \
  -H 'X-Request-Id: 8b4e1c2f' \
  -H 'Content-Type: application/json' \
  -d '{ "event_type": "alert.created", "data": { "message": "threshold exceeded" } }'

Sample incoming request, OAuth 2.0 client-credentials variant (exchange credentials at the token URL first, then send the bearer):

curl -X POST 'https://<your-ipaas-host>/inbound/<account_id>/<solution_uuid>/<runbook_uuid>' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'X-Request-Id: 8b4e1c2f' \
  -H 'Content-Type: application/json' \
  -d '{ "event_type": "alert.created", "data": { "message": "threshold exceeded" } }'

Output

Field	Type	Description
url_postfix	String	Trailing path segment after the runbook UUID. For /inbound/<account_id>/<solution_uuid>/<runbook_uuid>/customer_42 it would be customer_42. nil when the caller appends nothing.
query_params	Hash	Query-string parameters parsed from the request URL. Empty hash when the URL has no query string.
headers	Nested	Present only when the trigger's headers configuration is non-empty. Contains one field per declared header; array-type headers are split on ,\s+.
body	Nested	Parsed JSON body, structured according to body_schema.

Note: url_postfix and query_params are independent. The first comes from the URL path glob; the second from the URL query string. A single request can populate either, both, or neither.

Example Output

For the API-key request above:

{
  "url_postfix": "customer_42",
  "query_params": {
    "region": "eu"
  },
  "headers": {
    "X-Request-Id": "8b4e1c2f",
    "X-Tags": [
      "priority",
      "followup"
    ]
  },
  "body": {
    "event_type": "alert.created",
    "data": {
      "source": "external-system",
      "message": "threshold exceeded"
    }
  }
}

Error Handling

All validation failures return HTTP 400 Bad Request with a JSON body of the form { "error": "<message>" }.

Condition	Error message
Missing or mismatched API-key value	Invalid or missing API key.
Missing or mismatched Basic Auth credentials	Invalid basic authentication header.
Missing, expired, or invalid OAuth 2.0 bearer token	Invalid or missing bearer token.
Body is missing a field declared required in body_schema, or a field has the wrong type	Output invalid: <details>
A header declared required: true is absent from the request	Output invalid: <details>

Best Practices

• Declare every header you rely on in the headers configuration so it appears on trigger_output.headers.<name>. The connector discards undeclared headers.
• Set array: true on headers[] entries for multi-value headers (for example X-Forwarded-For or comma-separated tag lists). The connector splits on ,\s+.
• Use url_postfix (the trailing path segment, for example .../<runbook_uuid>/customer_42) to pass routing information and branch on trigger_output.url_postfix in the runbook. This keeps routing out of the request body.
• Make body_schema strict: mark every required field with required: true and use specific data types (integer, date_time, etc.) rather than free-form strings. The platform rejects non-conforming requests before the runbook starts.

Actions

None. This connector is inbound only.

Best Practices

• For outbound calls (from a runbook to an external system) use the HTTP connector. This connector handles inbound requests only.
• If multiple callers share one endpoint, assign each caller a distinct Basic Auth username/password pair (or a distinct API-key value) so request logs and audit trails clearly identify the caller.
• Branch on body.event_type or url_postfix inside the runbook instead of creating one trigger per event type. Fewer endpoints mean fewer credentials to manage and rotate.
• Pair this connector with the Ruby connector when downstream actions require additional validation or transformation of the incoming payload.
• Review and rotate API keys, Basic Auth credentials, and OAuth 2.0 client credentials whenever the set of calling systems changes.
• Prefer OAuth 2.0 client credentials whenever the calling system supports it. The endpoint receives only short-lived bearer tokens, while the stored client secret remains protected as a non-reversible credential.

Common Use Cases

• Monitoring alerts: Receive events from any monitoring tool that can POST JSON, then branch on body.event_type to route alerts to different incident-creation runbooks.
• ITSM webhooks: Accept ticket or change callbacks from third-party ITSM platforms with vendor-specific payloads by defining each vendor's schema in body_schema.
• Integration callbacks: Connect applications that can POST JSON using an API key, Basic Auth, or OAuth 2.0 client credentials, even if no dedicated connector exists.
• Request/response bridges: Pair this inbound trigger with the outbound HTTP connector to receive requests in one payload format and forward them in another.

References

• RFC 6749: The OAuth 2.0 Authorization Framework
• RFC 7617: HTTP Basic Authentication
• RFC 8259: JSON Data Interchange Format
• RFC 9068: JWT Profile for OAuth 2.0 Access Tokens