Rhythm 2.0 Specifications

Appearance

CAP-PFM-INT-013Retain and verify incoming provider notifications

Markdown

CAP-PFM-INT-013

Retain and verify incoming provider notifications

Markdown
  • DocumentDraft
  • Product intentProposed
  • ImplementationObserved

Planning

Feature
FEAT-PFM-INT-04
Exercised by
FAS-PFM-INT-04-01, FAS-PFM-INT-04-02, FAS-PFM-INT-04-04
Key concepts
CON-PFM-INT-004
Actors
ACT-PFM-006, ACT-PFM-021, ACT-PFM-017, ACT-PFM-018
Depends on
CAP-PFM-INT-004
Related
CAP-PFM-INT-015
Open questions
OQ-PFM-INT-002
Proved by
ATS-PFM-INT-013

Implementation

Executable suites
TST-PFM-INT-480, TST-PFM-INT-491, TST-PFM-INT-567, TST-PFM-INT-568, TST-PFM-INT-584

KindCapabilityProduct areaPlatformModuleIntegration access, customer extensions and shared workflow configurationRevision1

Read atservices-platform ad3f6a65react-console baf6dae3

Retain and verify incoming provider notifications ​

Purpose ​

Rhythm preserves provider notifications, verifies their origin and supports controlled reprocessing.

How It Works ​

A provider sends account notifications to an endpoint Rhythm provisions for the connection. Rhythm retains each message before acknowledging it. A worker asks the integration to verify and interpret the retained message. Accepted interpretations become events for application routing. Repeated provider sends are handled as duplicates. An operator can replay stored material after correcting a processing problem. Signing-secret setup and rotation support the endpoint’s authentication lifecycle. This machinery is implemented without an accepted webhook milestone. The product should approve its customer-facing recovery and secret-handling behaviour before design treats it as settled.

Relationships ​

  • Requires maintain a verified provider account connection to supply the prerequisite configuration or operation.
  • Connects with route integration events to their application owners through shared integration records.

The Formal Contract

The narrative above explains; the sections below are authoritative — the rules, scenarios and tests this document binds.

Outcomes
Durable storage precedes notification acknowledgement.Duplicate handling avoids repeated processing except during an explicit replay.Operators can reprocess retained messages following a correction.
Surfaces
apijobconsole
Intent sources
services-platform:docs/milestones/INTG-M3-webhooks-events-deliveries.md#Objective

Controls

36 controls apply, from the corpus control catalogue.

TC-AVL-001 TC-AVL-004 TC-AZ-001 TC-AZ-002 TC-AZ-003 TC-AZ-004 TC-CRY-001 TC-CRY-002 TC-CRY-003 TC-CRY-004 TC-DAT-001 TC-DAT-002 TC-DAT-003 TC-IAM-001 TC-IAM-006 TC-LOG-002 TC-LOG-003 TC-LOG-004 TC-LOG-005 TC-MON-001 TC-MON-002 TC-PI-001 TC-PI-002 TC-PI-003 TC-PI-004 TC-PI-005 TC-SEC-001 TC-SEC-002 TC-SEC-003 TC-SEC-004 TC-TEN-001 TC-TEN-002 TC-TEN-003 TC-VEN-001 TC-VEN-002 TC-VEN-003

Permissions

KeyChecked atScope
platform.integrations.readapitenant
platform.integrations.manageapitenant
platform.integration-executions.operateapitenant

Business Rules

9 rules, 9 to be proved before approval. A rule's product intent is derived from its origin: 0 confirmed by a product decision, the rest inheriting this capability's proposed.

IdRuleKindEnforced atProvenance
01must prove
Proposed
Ingress accepts messages only for enabled provisioned endpoints, returns bodyless not found otherwise, refuses bodies over one megabyte and throttles each endpoint above fifty requests per second.
proved by ATS-PFM-INT-013-01, TST-PFM-INT-567
validationapi, servicetest
services-platform:modules/integrations/tests/integration/services/webhooks/ingress.integration.spec.js#answers 404 for a disabled endpoint, and records nothing
02must prove
Proposed
Ingress stores body and headers before recording and queueing the notification or acknowledging receipt, omitting authorization and cookies unless verification requires them.
proved by ATS-PFM-INT-013-02, TST-PFM-INT-567, TST-PFM-INT-584
invariantservicetest
services-platform:modules/integrations/tests/integration/services/webhooks/ingress.integration.spec.js#stores the body and headers, then records the event pending and queued with its digest and a queue row
03must prove
Proposed
Registration-challenge endpoints verify and return the adapter’s challenge response inline.
no proof recorded yet
policyservicetest
services-platform:modules/integrations/tests/integration/services/webhooks/ingress.integration.spec.js#answers a registration challenge inline with the adapter’s response, after verifying it
04must prove
Proposed
The worker verifies stored notifications with endpoint secrets, rejects invalid signatures without events and queues events from verified messages; retryable failures follow six asynchronous attempts and permanent failures stop immediately.
proved by ATS-PFM-INT-013-03, ATS-PFM-INT-013-10, ATS-PFM-INT-013-11, ATS-PFM-INT-015-10, TST-PFM-INT-480, TST-PFM-INT-568
lifecycleservicetest
services-platform:modules/integrations/tests/integration/services/webhooks/webhook-worker.integration.spec.js#rejects a request whose signature does not verify, writing no event
05must prove
Proposed
Processed provider event identifiers remain duplicates permanently, body duplicates on the same endpoint remain duplicates for twenty-four hours when no event identifier exists, and explicit replay bypasses both checks.
proved by ATS-PFM-INT-013-04, ATS-PFM-INT-013-10, TST-PFM-INT-480, TST-PFM-INT-568
invariantservice, databasetest
services-platform:modules/integrations/tests/integration/services/webhooks/webhook-worker.integration.spec.js#ignores a second request with the provider event id of one already processed, pointing at the first
06must prove
Proposed
Verification provisions declared endpoints with minted secrets, and manually registered endpoints expose their address and secret once to an authorized administrator.
proved by ATS-PFM-INT-004-15, ATS-PFM-INT-005-17, ATS-PFM-INT-013-05, ATS-PFM-INT-013-09, ATS-PFM-INT-013-12, ATS-PFM-INT-013-13, TST-PFM-INT-480, TST-PFM-INT-491
policyservice, apitest
services-platform:modules/integrations/tests/e2e-adapters/events-dummy.adapters.spec.js#never answers the secret again
07must prove
Proposed
Secret rotation accepts both old and new signing secrets for twenty-four hours and then accepts only the replacement.
proved by ATS-PFM-INT-013-06, ATS-PFM-INT-013-09, TST-PFM-INT-568
lifecycleservicetest
services-platform:modules/integrations/tests/integration/services/webhooks/webhook-worker.integration.spec.js#verifies with the previous secret too while the endpoint rotates
08must prove
Proposed
Operators may replay an individual stored message or an endpoint window no longer than seven days, with each replay entering history.
proved by ATS-PFM-INT-013-07
policyapi, servicedocumented
services-platform:docs/integrations/README.md#Webhooks (WS8, 2026-10-18)
09must prove
Proposed
Integration readers inspect endpoint and notification records without signing-secret values.
origin: services-platform:docs/milestones/INTG-M1-find-install-connect.md#D4
proved by ATS-PFM-INT-013-08, TST-PFM-INT-491
permissionapitest
services-platform:modules/integrations/tests/e2e/reader-access.e2e.spec.js#reads no webhook signing secret in any answer

Scenarios

IdGivenWhenThenProvenance
01The test provider posts a payment-state notification.Rhythm verifies and processes the retained message.A payment update is routed to Accounting and acknowledged.test
services-platform:modules/integrations/tests/e2e-adapters/events-dummy.adapters.spec.js#reaches Accounting’s consumer, which acknowledges it

The Markdown files under specs/ in rhythmsoftware/rhythm-v2-docs are the canonical source of truth. This reader is a generated, read-only projection of them.

Rhythm Software