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 or HTTP Basic Auth credentials for the caller. Populate whichever method the calling system supports. You can configure both on the same connection. Leave a method blank to disable it.
• A caller system able to send JSON POST requests to the trigger URL over HTTPS.

Authentication

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

API key

Basic auth

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 or Basic Auth. Common callers include monitoring tools, ITSM platforms, and custom integrations with no dedicated connector.

Input Parameters

headers[] fields

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" } }'

Output

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>" }.

Best Practices

• Declare every header you rely on in the headers config so it appears on trigger_output.headers.<name>. The connector discards undeclared headers.
• Set array: true on headers[] entries for multi-value headers (e.g. X-Forwarded-For, comma-separated tag lists). The connector splits on ,\s+.
• Use url_postfix (the trailing path segment, e.g. …/<runbook_uuid>/customer_42) to pass routing info and branch on trigger_output.url_postfix in the runbook. This keeps routing out of the body.
• Make body_schema strict: mark every required field required: true and pick specific types (integer, date_time, etc.) rather than free-form strings. The platform rejects non-conforming bodies at the edge instead of failing mid-runbook.

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 only.
• If multiple callers share one endpoint, give each a distinct Basic Auth username/password pair (or distinct API-key value) so request logs and audit trails distinguish them.
• Branch on body.event_type or url_postfix inside the runbook rather than standing up one trigger per event type. Fewer endpoints means fewer credentials to rotate.
• Pair with the Ruby connector when downstream actions need a reshaped or validated version of the incoming body.
• Review and rotate API-key and Basic Auth credentials whenever the set of caller systems changes.

Common Use Cases

• Monitoring alerts: receive events from any monitoring tool that can POST JSON, then branch on body.event_type to fan out to different incident-creation runbooks.
• ITSM webhooks: accept ticket or change callbacks from third-party ITSM platforms with vendor-specific payloads by declaring each vendor's fields in body_schema.
• Integration callbacks: wire up any app that can POST JSON with Basic Auth or an API key, even for apps with no dedicated connector.
• Request/response bridges: pair this inbound trigger with the outbound HTTP connector to accept requests in one payload shape and forward them in another.

References

• RFC 7617: HTTP Basic Authentication
• RFC 8259: JSON Data Interchange Format