Webhooks

Current webhook surface

Pinrail already exposes a live webhook-management workflow in the TMS account and terminal feeds surfaces. The current product shape is not just a future plan: accounts can register webhook destinations, attach event subscriptions, and send signed test deliveries from the portal today.

Where webhook setup lives today

The current workflow is centered on the TMS webhooks tab:

• Account -> Webhooks
• terminal feed and alert surfaces under the terminal detail pages

The account webhooks page currently includes:

• Webhook Destinations
• Event Subscriptions
• Subscription Catalog
• Recent Webhook Activity

Delivery format

Current webhook deliveries use:

• User-Agent: pinrail-tms-alerts/1.0
• Content-Type: application/json
• X-Pinrail-Signature: sha256=<hex-hmac>

The signature is an HMAC-SHA256 of the raw request body using the webhook secret configured for the destination.

Test delivery behavior

The account webhooks flow can send a signed test event immediately after a destination is created.

Current test payload behavior includes:

• event_type: "test"
• summary: "Pinrail test webhook"
• account-scope identifiers in the JSON payload
• a tms_url pointing back to the relevant account webhooks surface

Current event categories

The live terminal and account surfaces already advertise event coverage for:

• terminal heartbeat stale
• processor outage
• communication flapping
• cash low
• cash out
• dispenser fault
• compliance expiration
• location risk change
• decline spike
• approval rate drop
• reversal spike
• repeated same-card attempt
• command failed
• provisioning failed
• settlement mismatch

Terminal feed coverage also renders event families such as:

• ATM online / offline status changes
• queued command updates
• recent alert activity
• switch-journal-linked operational events

Operational guidance

Webhook consumers should:

1. verify X-Pinrail-Signature against the raw body
2. reject requests signed with an unknown secret
3. persist delivery identifiers and event timestamps before side effects
4. treat deliveries as retry-safe and at-least-once
5. log the source TMS URL and scope identifiers for auditability

Relationship to the broader contract

Webhook events are best treated as the asynchronous companion to the integration catalog and read APIs:

• use GET /v1/integrations/catalog to discover the current event families by service
• use report and terminal APIs for point-in-time reads
• use webhook subscriptions when a sponsor-bank or operator workflow needs change notification without polling

What is still evolving

The current webhook contract is strongest around alerting, telemetry, transaction-risk signals, provisioning outcomes, and settlement-adjacent exceptions. Additional schema-level examples and frozen public payload contracts can be layered on top of this live signed-delivery foundation.