External systems integration guide

• Copy a newly issued secret immediately and store it in your secret manager, never in source or browser code.
• Use separate keys for development, staging and production so a test integration cannot reach production records or runs.
• Send X-API-Key and X-App-Instance-Guid on Data and Automation Client-tier calls. Copy the environment base URL and instance GUID from the product integration screen; do not infer either from another environment.
• Data keys support read/write grants, optional source-IP ranges, expiry, and per-minute/per-hour limits. Automation keys support start/read grants per workflow, optional source-IP ranges, and expiry.
• Record an owner and expiry date. Data rate limits report X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset; a 429 also supplies Retry-After. X-RateLimit-Reset and Retry-After are both a number of seconds to wait, not a timestamp, so add them to the current time rather than reading them as one.
• Data API-key callers see published schemas, not a working draft that is still being modeled.

1. 01

   Publish the record type

   Resolve breaking-change and migration warnings before treating the new version as an integration contract.

2. 02

   Mint a narrow key

   Limit it to the record types the source owns and set request limits appropriate to its traffic.

3. 03

   Read the generated schema

   Use the schema and generated API reference for exact field names, types, required values and the record-type URL.

4. 04

   Choose single or bulk writes

   Use the flat record endpoint for one record and the flat bulk endpoint for batches. A bulk request still counts every row against quota.

5. 05

   Persist the response identifiers

   Keep the record GUID and source correlation identifier so later updates and support investigations address the same record.

POST /v1/egav/client/entity/{record_type}/attribute-set/{schema}/v{version}/flat/
X-API-Key: <data-api-key>
X-App-Instance-Guid: <data-app-instance-guid>
Content-Type: application/json

{
  "external_id": "crm-87421",
  "status": "received"
}

{
  "data": {
    "id": 42,
    "guid": "<stable-record-guid>",
    "external_id": "crm-87421",
    "status": "received"
  },
  "success": true,
  "status": "success"
}

• Use the record GUID as the durable external identifier. Single-record reads accept either the numeric id or GUID.
• List responses add meta.total, meta.page, meta.per_page and meta.total_pages. Keep per_page between 1 and 100.
• If the schema is live-on-save, the write is immediately readable. If controlled publishing is enabled, call POST .../flat/{id}/publish before Client-tier reads can see the new working state.
• The generated Data write surface does not currently expose a request-level idempotency key. Make a source identifier such as external_id unique and reconcile an uncertain outcome before creating again.

POST /v1/automation/client/workflows/{workflow_code}/start
X-API-Key: <automation-api-key>
X-App-Instance-Guid: <automation-app-instance-guid>
Content-Type: application/json

{
  "workflow_id": "order-87421",
  "idempotency_key": "start:order-87421:v1",
  "subject": {"type": "entity", "source_app_code": "egav", "source_app_instance_guid": "<data-app-instance-guid>", "entity_type": "order", "guid": "<record-guid>"},
  "input": {"order_id": "87421"},
  "metadata": {"source": "commerce-api"}
}

1. 01

   Register the source

   Create an external system, mark it as an event source and copy its generated inbound secret.

2. 02

   Bind the workflow

   Choose the external source and event type, add filters, validate the workflow, publish it and arm the trigger.

3. 03

   Serialize once

   Create the final UTF-8 JSON bytes. Compute the HMAC over those exact raw bytes; do not parse and reformat after signing.

4. 04

   Post to the displayed inbound URL

   POST /v1/automation/public/webhooks/{app_instance_guid}/{source_code}/inbound with X-Signature-256: sha256=<hex>. This HMAC is the credential; do not send a bearer token.

5. 05

   Keep the returned run identity

   Store the workflow and run identifiers beside your source event id for status checks and support.

raw = UTF8(JSON body)
digest = HMAC_SHA256(inbound_secret, raw).hex()
X-Signature-256: sha256=<digest>

{
  "event_id": "commerce:event:87421",
  "event_type": "order.ready",
  "data": {"order_id": "87421", "total": 125.50}
}

1. 01

   Choose the system

   Use an available supplied External System. For a custom API, register its base URL, authentication, retry policy, throttling and concurrency limits.

2. 02

   Select operations

   Managed systems supply protected activities and entity definitions. For a custom system, fetch or upload an API description and import only useful operations.

3. 03

   Define a custom operation

   If your custom service has no usable description, provide the method, path, typed input and output, and whether the response is synchronous.

4. 04

   Choose the account

   Select the named private account connection for the activity and review its permission check before running.

5. 05

   Map inputs

   Map from the trigger, an earlier step output, a signal, a fixed value, a template or a computed value.

6. 06

   Map outputs and arm

   Map useful response values back to later steps or records. Arming compiles and validates the resolved mappings.

1. 01

   Connect inside the system

   Open the External System configuration and its connection settings. Use New connection, set Connection name and Authentication, then authorize the account or supply the credentials required by that option. OAuth uses service consent; API keys, bearer credentials and username/password use their declared fields.

2. 02

   Bind the exact account

   A system can have multiple private accounts. In the workflow activity, use Choose your account connection to select the intended named account. Accounts are scoped to their owner and workspace. Workflow access records the owner approval needed for scheduled or event-driven use.

For Jira and HubSpot, run a controlled read with the intended named connection and check the provider-side result before enabling create or update activities. A supplied catalog entry or saved connection does not prove provider access.

Requested permissions describe the Authentication option: they do not confirm what your account has granted. Compare them with Required permission identifiers for the activity. Every required group must be satisfied; a group can offer alternative permissions. Read the account check message and use Check permissions again after a change. Automation checks again when the activity runs.

Verify local and production behavior separately with a controlled account and a useful activity. Check the selected account, mapped data and provider-side result, then prove denied access and the applicable refresh, reconnect and alert behavior. A catalog entry, successful login or saved connection alone does not prove an activity works.

• HTTPS receivers get the CloudEvents 1.0 JSON body and the managed X-Signature-256 header.
• Data also sends X-EGAV-Event, X-EGAV-Event-Id, X-EGAV-Delivery and X-EGAV-Subject. Automation uses the corresponding X-Automation-Event, X-Automation-Event-Id, X-Automation-Delivery and X-Automation-Subject headers.
• Amazon SQS is useful for buffering, Amazon SNS for fan-out, and Kafka for an existing event stream.
• Create different subscriptions for consumers with different ownership, event filters, credentials or recovery needs.
• Use the test-delivery action before enabling business processing; a successful DNS lookup is not proof your handler accepts and verifies the event.

1. Read the raw request bytes
2. Compute HMAC-SHA256(secret, raw bytes)
3. Constant-time compare "sha256=<hex>" with X-Signature-256
4. Parse the CloudEvents 1.0 JSON
5. Reject an unexpected source or event type
6. Insert event id into a unique processed-events store
7. Apply the business change once
8. Return 2xx only after durable acceptance

• The default is four total attempts: one immediate attempt, then retries after 10, 60 and 300 seconds. The default per-attempt timeout is 10 seconds.
• A subscription can set 1–10 total attempts, a 1–120 second timeout and 1–10 backoff delays; each delay must be between 1 second and 24 hours.
• Return a non-2xx response for a transient failure so delivery can retry; do not return success before the event is durably queued or committed.
• Delivery is at least once. A duplicate event is normal and should return success after your unique event-id check finds the prior result.
• Inspect each attempt in the delivery log. Failed deliveries back off and eventually dead-letter when their attempt budget is exhausted.
• Fix the receiver first, then retry one delivery or use bulk redrive. Redrive does not replace receiver-side idempotency.

• Retry Automation starts with the same JSON idempotency_key and signed inbound sends with the same event_id.
• Data writes have no request-level idempotency key. Use a unique source external_id and query or reconcile after an uncertain response before creating again.
• Automation execution status values are pending, running, completed, failed, cancelled, timeout and skipped.

1. 01

   Create a second API key

   Mint a separately named key with the same minimum grants. Do not rotate the existing key yet.

2. 02

   Deploy and prove the new value

   Change the secret-manager reference, restart or redeploy the consumer, and make a controlled request.

3. 03

   Retire the old API key

   Revoke it only after logs show that no caller still presents it.

4. 04

   Treat rotate as an atomic replacement

   Rotation invalidates the old secret immediately for Data keys, Automation keys, inbound source secrets and outbound webhook signing secrets.

5. 05

   Coordinate inbound HMAC rotation

   Pause sends or coordinate an atomic sender cutover because a request signed with the previous source secret will be rejected.

6. 06

   Separate outbound subscriptions when overlap is needed

   Use a temporary second subscription and let the receiver accept both subscription secrets. Expect duplicate business events during the overlap and deduplicate by CloudEvents id, then remove the old subscription.