Product integration reference #

Product integrations connect a published Product Instance to bounded HTTPS workflows. Outbound bindings are invoked by Rules, Operations, or Processes. Inbound endpoints accept only allowlisted events and Operations.

Configure integrations under Access, publish the application, and attach that version to the customer portal. The resulting Product Instance provides the tenant boundary for delivery and receipts.

Configure outbound HTTPS #

An HTTPS integration binding has a stable binding key and a public HTTPS destination. Destinations with embedded credentials, unresolved hosts, or private and non-public addresses are rejected. Redirects are not followed.

Supported methods are:

GET
POST
PUT
PATCH
DELETE

POST, PUT, and PATCH send the integration request as JSON. GET sends no request body. DELETE sends JSON only when it has a payload.

The configured timeout must be from 1 to 10 seconds. Responses are bounded to 64 KiB. These limits keep an application execution from becoming an unbounded HTTP client.

Attach managed credentials #

A binding can refer to an application-managed credential by credential_key. Supported credential kinds are:

bearer, sent in the Authorization header
basic, built from the managed username and secret
api_key_header, sent in its configured header or X-API-Key

Secrets are encrypted at rest and are not copied into delivery responses. Rotate or revoke the managed credential rather than embedding credentials in the destination URL, application definition, or field-device software.

Outbound requests also carry Idempotency-Key and X-Correlation-ID. Preserve those identifiers in the receiving system's audit and deduplication records.

Choose synchronous or durable delivery #

delivery_mode accepts sync, submit, or async.

sync performs the bounded HTTPS call in the invoking execution and records an integration invocation as succeeded, failed, or noop. A successful HTTP response confirms that the destination accepted the request, not that its business process completed.

submit and async create a durable delivery. The invocation response reports mode: "durable", delivery_id, delivery_status, and attempt_count. Acceptance of a queued delivery is not final delivery.

Follow durable delivery status #

A durable delivery uses these status values:

queued
attempting
retry_wait
succeeded
dead_letter
failed_permanent
cancelled
expired

Each HTTP attempt records its attempt number, timestamps, HTTP status, bounded response, error, and whether the failure was retryable.

HTTP 408, 425, 429, and 5xx responses are retryable. A missing response or network/runtime failure is also retryable. Other unsuccessful HTTP statuses become failed_permanent.

The binding's max_attempts must be from 1 to 20 and defaults to 8. Retry wait starts at 15 seconds and doubles to a maximum of 15 minutes. Exhausting retryable attempts moves the delivery to dead_letter.

An operator can replay a delivery in dead_letter, failed_permanent, or expired. Replay requeues it for another attempt cycle and records Product Activity. Earlier attempt records remain part of the delivery history.

Use the delivery's idempotency key at the destination. Replay and retry prevent duplicate Dataplicity delivery intent where possible; they cannot guarantee an exactly-once third-party side effect.

Configure an inbound endpoint #

An inbound endpoint belongs to one Product Instance. Its allowed_actions contains explicit {type, key} pairs, where type is event or operation. The endpoint rejects any action not on that allowlist.

Dataplicity returns the plaintext endpoint secret when the endpoint is created and stores only its hash. Send it in X-Product-Inbound-Secret. Revoke and replace the endpoint when its secret or ownership changes.

An inbound request contains:

json

{
  "action": {
    "type": "event",
    "key": "erp.sync"
  },
  "payload": {
    "order_id": "A1"
  },
  "idempotency_key": "erp-event-A1",
  "correlation_id": "order-A1"
}

The idempotency_key is required. correlation_id is optional.

Sign inbound requests #

The endpoint secret always authenticates the request. A sender can additionally put an HMAC-SHA256 digest of the exact request body in X-Product-Signature, either as a hexadecimal digest or prefixed with sha256=.

When the signature header is present, an invalid digest returns 401. The secret header must still be present; the HMAC does not replace endpoint authentication.

Handle receipts and rate limits #

The endpoint applies its configured per-minute rate limit and returns 429 when the limit is exceeded. Rate limiting occurs after authentication and allowlist validation.

Dataplicity stores one inbound receipt for each endpoint and idempotency key. The first accepted action normally returns 201 with created: true. Repeating the same key returns the stored receipt with 200 and created: false, without creating another event or Operation invocation.

Choose idempotency keys that identify one sender-side intent. A receipt proves that Dataplicity deduplicated ingestion; follow the Operation state and authoritative product state when an action has downstream effects.