Enhanced RTP Tracking Webhook

Overview

The Enhanced RTP Payment Tracking webhook provides customers with near-real-time, event-driven updates for RTP payment lifecycle changes. It allows customer ERP, treasury, reconciliation, customer service, and payment operations systems to receive authoritative payment status changes without polling MassPay.

Webhook events are delivered when material RTP lifecycle changes occur, including submission, network acknowledgement, settlement, returns, and notices of change. Customers should treat webhook payloads as system-to-system notifications and process them idempotently because delivery is at-least-once.

Webhook Endpoint & Customer Configuration

Delivery method: POST
Customer endpoint: Customer-provided HTTPS URL registered with Convera during onboarding.
Event family: RTP payment tracking events.
Supported event types: rtp.payment.status.changed, rtp.payment.returned, and rtp.payment.notice_of_change.
Content type: application/json
Delivery model: At-least-once delivery with retry for failed or timed-out attempts.

Customers must provide an externally reachable HTTPS endpoint, configure any required allow listing, and store the signing secret or certificate information provided during implementation. Production webhook delivery should be enabled only after successful sandbox validation.

Request Headers Sent by Convera

Header	Required	Description
Content-Type	Yes	Always application/json.
X-Correlation-Id	Yes	Identifier used for tracing the event across Convera and customer systems.
X-Webhook-Event-Id	Yes	Unique event identifier. Use this value for idempotency and duplicate detection.
X-Webhook-Timestamp	Yes	UTC timestamp when the webhook request was generated.
X-Webhook-Signature	Yes	Request signature generated using the configured signing method. Customers must validate this before processing the event.
User-Agent	Recommended	Identifies Convera webhook delivery infrastructure.

Webhook Payload Specification

All RTP tracking webhooks follow a common envelope containing event metadata, customer identifiers, payment identifiers, status information, amount details, and RTP network context. Event-specific objects provide additional details for returns and notices of change.

Field	Type	Description
eventId	string	Unique event identifier. Matches X-Webhook-Event-Id.
eventType	string	Webhook event type, for example rtp.payment.status.changed.
eventVersion	string	Payload contract version.
occurredAt	string	UTC timestamp when the underlying RTP lifecycle event occurred.
customerId	string	Convera-assigned customer identifier.
paymentId	string	Convera MassPay payment identifier.
customerPaymentId	string	Customer-supplied payment reference where available.
batchId	string	MassPay batch identifier where the RTP payment was submitted as part of a batch.
sequence	number	Monotonic sequence number per payment used to handle out-of-order delivery.
status.previous	string	Previous canonical RTP status.
status.current	string	Current canonical RTP status.
amount	object	Payment amount and currency.
rtp	object	RTP network context, including standard entry class, trace number, effective entry date, settlement date, and raw network status where available.
return	object	Present for rtp.payment.returned events. Includes return code, reason, return date, and related references.
noticeOfChange	object	Present for rtp.payment.notice_of_change events. Includes correction code and corrected fields.

Example Webhook Payloads

Example RTP Status Change Event

{
  "eventId": "evt_rtp_01J8Y9X7Q2V6M5N4P3R2T1S0A9",
  "eventType": "rtp.payment.status.changed",
  "eventVersion": "1.0",
  "occurredAt": "2026-09-17T10:15:30Z",
  "customerId": "cust_123456",
  "paymentId": "pay_95a147ec986a4c25b569a96955340d9b",
  "customerPaymentId": "ERP-RTP-20260917-001",
  "batchId": "batch_NTR7865170",
  "sequence": 4,
  "status": {
    "previous": "ACCEPTED_BY_NETWORK",
    "current": "SETTLED",
    "description": "RTP payment settled successfully"
  },
  "amount": {
    "currency": "USD",
    "value": 1250.75
  },
  "payer": {
    "name": "ACME INC",
    "accountMasked": "******6655"
  },
  "beneficiary": {
    "name": "ACME SUPPLIER LLC",
    "accountMasked": "******6789"
  },
  "rtp": {
    "standardEntryClass": "CCD",
    "companyEntryDescription": "PAYMENT",
    "traceNumber": "091000019123456",
    "effectiveEntryDate": "2026-09-17",
    "settlementDate": "2026-09-18",
    "rawNetworkStatus": "SETTLED"
  },
  "metadata": {
    "correlationId": "corr_6d7f9f0a2b4c",
    "source": "RTP_NETWORK",
    "environment": "production"
  }
}

Example RTP Return Event

{
  "eventId": "evt_rtp_return_01J8Y9X7Q2V6M5N4P3R2T1S0B1",
  "eventType": "rtp.payment.returned",
  "eventVersion": "1.0",
  "occurredAt": "2026-09-19T14:22:10Z",
  "customerId": "cust_123456",
  "paymentId": "pay_95a147ec986a4c25b569a96955340d9b",
  "customerPaymentId": "ERP-RTP-20260917-001",
  "batchId": "batch_NTR7865170",
  "sequence": 5,
  "status": {
    "previous": "SETTLED",
    "current": "RETURNED",
    "description": "RTP payment returned by receiving bank"
  },
  "amount": {
    "currency": "USD",
    "value": 1250.75
  },
  "return": {
    "code": "R03",
    "reason": "No account / unable to locate account",
    "returnDate": "2026-09-19",
    "originalTraceNumber": "091000019123456",
    "rawReturnCode": "R03"
  },
  "rtp": {
    "standardEntryClass": "CCD",
    "traceNumber": "091000019123456",
    "effectiveEntryDate": "2026-09-17",
    "settlementDate": "2026-09-18"
  },
  "metadata": {
    "correlationId": "corr_6d7f9f0a2b4c",
    "source": "RTP_RETURN_FILE",
    "environment": "production"
  }
}

Status Outcomes & Customer Handling Matrix

Canonical Status	Description	Recommended Customer Action
CREATED	Payment has been created in MassPay but not yet submitted to the RTP network.	Record initial state. Do not treat as submitted or settled.
PENDING_SUBMISSION	Payment is awaiting RTP file generation or submission window.	Display as pending. Avoid duplicate submissions unless explicitly cancelled and recreated.
SUBMITTED_TO_NETWORK	Payment has been included in an RTP submission.	Update ERP or treasury system to submitted. Continue monitoring for acceptance, settlement, or return.
ACCEPTED_BY_NETWORK	RTP network or processing bank has accepted the item for processing.	Mark as accepted but not yet final. Continue monitoring for settlement and returns.
SETTLED	Payment has settled through the RTP process.	Reconcile payment as settled, while retaining monitoring for potential post-settlement returns.
RETURNED	Payment was returned by the receiving bank or RTP network.	Reverse or exception the payment in downstream systems. Review return code and contact beneficiary if needed.
CANCELLED	Payment was cancelled before submission where cancellation is supported.	Mark as cancelled and ensure no beneficiary credit is expected.
FAILED	Payment failed before successful RTP submission due to validation, processing, or technical error.	Route to repair or operational exception handling. Do not treat as sent or settled.

Delivery, Retries & Idempotency

Acknowledge quickly: Customer endpoints should return a 2xx response only after the event has been safely persisted or queued.
Deduplicate events: Store and check eventId or X-Webhook-Event-Id. Duplicate deliveries of the same event must not create duplicate ledger entries, notifications, or workflow actions.
Handle out-of-order delivery: Use paymentId, sequence, and occurredAt to apply events in the correct lifecycle order.
Retry behaviour: Convera retries delivery for timeouts and non-2xx responses using exponential backoff within the configured retry window.
Do not block processing: Webhook receivers should enqueue events for asynchronous processing and avoid long-running synchronous work inside the HTTP request.

Security, Validation & Best Practices

Transport security: Expose only HTTPS endpoints using TLS 1.2 or later. Mutual TLS may be configured where required.
Signature validation: Validate X-Webhook-Signature and X-Webhook-Timestamp before trusting or processing payloads.
Replay protection: Reject requests with timestamps outside the agreed tolerance window and ignore duplicate eventId values already processed.
Data protection: Do not log full account numbers or sensitive beneficiary information. Store masked payloads where possible and apply customer data retention policies.
Operational monitoring: Track webhook ingestion success, processing latency, duplicate rates, failed signature validations, return-code distribution, and notice-of-change frequency.
Fallback process: If webhook processing is unavailable, queue incoming events and reconcile against MassPay records once service is restored.