The custom HTTP Action contract

Expose one dedicated HTTPS endpoint#

Use a public endpoint such as https://support.example.com/reesponder/order-status. The example domain is a placeholder: replace it with your own service. Configure its URL without a query string or fragment. The service should authenticate Reesponder, authorize the requested record and return only customer-safe information.

Business supports GET reads. Scale also supports POST writes after visitor confirmation. Reesponder does not support arbitrary method selection, OAuth exchanges or arbitrary custom request-header configuration in the HTTP form. If another service expects a different protocol, put a narrow adapter in front of it.

A production adapter should expose this contract directly. Do not forward arbitrary customer text into an unrestricted upstream API or let an input become the destination URL. The saved endpoint is fixed for the Action revision.

Headers on both request types#

Accept: application/json
Idempotency-Key: 1b540ead-b35b-41c9-94b5-4d592d5feab1
Authorization: Bearer YOUR_SERVER_SIDE_TOKEN

The Authorization header is sent only if a bearer token is saved. The UUID is an illustrative run reference; each actual run has its own value. POST also sends Content-Type: application/json. Validate the bearer token in your service before looking up or writing records.

Keep the run reference in operational logs so a destination result can be correlated with Activity & requests. Redact Authorization in those logs. The reference is useful for recovery; the credential is not useful in a shared incident record.

GET lookup parameters#

GET /reesponder/order-status?order_reference=ORDER-1042&verified_email=buyer%40example.com

Configured input strings become query parameters. After widget email verification, Reesponder adds verified_email. Without a verified identity, that parameter is not supplied. Keep verification enabled for private customer information and match the supplied email to the owner of the requested record on your server.

A reference number alone does not prove ownership. Return a generic not-found or unavailable response when the identity does not match; avoid revealing whether another customer’s record exists. A GET endpoint must not place orders, reserve inventory or trigger messages as a side effect.

Because inputs use the query string, configure your own access logs and monitoring to avoid unnecessary private-data copies. A verified email on a request proves the bounded widget check, not permission to return every record associated with that address.

POST operation body#

{
  "inputs": {
    "order_reference": "ORDER-1042",
    "request_details": "Please change the delivery date."
  },
  "customer": {
    "verifiedEmail": "[email protected]"
  },
  "idempotencyKey": "1b540ead-b35b-41c9-94b5-4d592d5feab1"
}

The body’s idempotency key matches the header. If identity verification is disabled and no verified email is available, customer is null. Never make private authorization depend on a separately collected, unverified email inside inputs.

Validate input values, ownership and current business state, then deduplicate the operation atomically using the idempotency key. Return the same recorded result for a replay. Do not invent a new mutation when a client asks about an existing run.

If your upstream provider cannot accept Reesponder's JSON shape, the adapter performs that translation after validation. Keep the public contract stable even when the upstream system's API or authentication changes.

Successful responses#

HTTP/1.1 200 OK
Content-Type: application/json

{"status":"Received","reference":"REQ-1042"}

Return a 2xx status and valid JSON with application/json content type. Configure mappings for status and reference, using readable labels. The body limit is 65,536 bytes; only mapped scalar results are delivered to the widget. Redirects, HTML error pages and compressed bodies that cannot be parsed are not supported.

A deliberate non-2xx response becomes provider_rejected. The private provider response body is not shown as an arbitrary customer-facing error. Keep diagnostic details in your own logs using the run reference, and use a useful 2xx status summary for a known, authorized business result.

Use an explicit output for ordinary business outcomes such as no eligible delivery date or a request waiting for review. A transport success must not be confused with completion of an asynchronous task.

An importable read configuration#

{
  "name": "Check order status",
  "description": "Look up the current status of an order owned by the verified customer.",
  "provider": "http",
  "mode": "read",
  "config": {
    "endpoint": "https://support.example.com/reesponder/order-status",
    "identityRequired": true,
    "requestType": "support",
    "fields": [{"key":"order_reference","label":"Order reference","required":true}],
    "outputs": [{"path":"status","label":"Status"},{"path":"reference","label":"Order"}]
  }
}

Save this JSON as a template, replace the endpoint, import it in Actions and choose your website. Credentials stay outside the template. Save, test an owned and an unowned record, inspect the result and enable the current revision only when both authorization paths behave correctly.

The endpoint shown here is an unusable example until replaced with your deployed service. The template intentionally contains no bearer credential, website ID, workspace ID or enabled state.

Worked example: accept a change request durably#

A customer asks to change the delivery date of an owned order. Your handler authenticates the service bearer token, reads customer.verifiedEmail, loads the referenced order and checks ownership. It then validates the requested date against current policy and availability. Visitor confirmation does not bypass these checks.

Inside a transaction, claim the supplied idempotency key and record the request's outcome. If that key already has a completed outcome, return the recorded result. If a key is already being processed, use your documented concurrency handling rather than starting another mutation. The exact storage design belongs to your service.

Return {"status":"Request received","reference":"REQ-1042"} only after the request is durably stored. The result does not claim that the courier date has changed. If the owning system completes the change synchronously, return the factual completed state instead.

If the reply is lost after storage commits, correlate the original run reference with the destination ledger. Reesponder may mark an external write unknown. A new proposal has a different key and can represent a second request, so resolve the first outcome before asking the customer to confirm another.

Contract tests before enabling#

Exercise authentication, ownership, required-string validation, a small valid result and a known normal business rejection. Check a redirect, HTML error body and a deliberately oversized result to understand how transport failures appear. None should cause an unrestricted private response to enter the customer conversation.

For a write, replay the same key and verify one mutation with the same recorded result. Test concurrent duplicates in your destination integration tests as well as a lost reply. Compare the result with the real stored record before enabling the current saved revision.

Separate the adapter from the business operation#

The adapter has two boundaries. At its public edge it accepts Reesponder's fixed GET or POST contract and service authentication. At its business edge it calls only the downstream operation that the configured task permits. It must not become a general proxy that accepts arbitrary hosts, methods or provider payloads from customer inputs.

Translate input strings into validated business values. For example, parse a requested quantity into an allowed integer and check current inventory before a write. Look up a private record only after matching the verified email according to your application's ownership model. Apply any additional authorization the task requires.

Translate the provider's response into a stable customer summary. A raw provider object can contain addresses, notes, permissions or internal debug fields that are inappropriate for chat. Return a deliberate object with the few scalar paths your Action maps. Keep upstream diagnostic details in protected logs.

This separation lets you update provider authentication or API versions without asking the customer widget to understand them. If you change the adapter's public endpoint or result shape, coordinate the saved Action update, retest its current revision and inspect the first live run.

Keep a useful recovery record#

For each write, store the idempotency key, a safe operation summary, processing state and final result in your destination's controlled records. The reference lets staff answer whether an uncertain request was accepted. Do not store verification codes or bearer tokens alongside it.

Decide how the handler responds while an earlier request with the same key is still running. A second request must not race the first into a duplicate mutation. Decide how long replay information remains available for your business process and how it relates to your own retention duties. Reesponder's conversation history is not that ledger.

Use the reference in service logs and make sure the team can locate it without searching entire private request bodies. Record timestamps and a bounded error category. A timeout and a known business rejection deserve different recovery steps even if both prevented a confirmed customer result.

There is no generic provider-status endpoint configured by the HTTP form. The widget's status refresh reads Reesponder's stored run state. If your business needs remote reconciliation, implement and operate that process on your side; do not promise that repeatedly pressing the widget control reruns or completes the mutation.