Integration Guides

Eclipse Notifications

Eclipse publishes real-time events to your systems whenever significant state changes occur on the platform. This section covers the two main notification mechanisms:

Outbound Webhooks (Wallet Movement Notifications)

Eclipse calls your pre-registered callback URL whenever a transaction affects a wallet. This is the primary mechanism for keeping your application in sync with real-time wallet state.

Key characteristics:

  • Eclipse calls your endpoint via HTTP POST with a JSON payload describing the event
  • Callbacks are retried with exponential back-off until your endpoint returns HTTP 2xx — see Callback Retries for the retry schedule
  • Callback URLs are configured at the wallet type level or per individual wallet
  • Payloads are signed with HMAC if HMACOutboundSignatureKey is configured for the tenant

See Wallet Movement Notifications for the full event schema and the Event Dictionary for all published event types.

Tenant-Initiated Notifications

Your application can use Eclipse to send notifications to your customers via SMS, email, or in-app push notifications (Firebase Cloud Messaging).

See Tenant-Initiated Notifications for the notifications endpoint, supported gateways, and Mustache template format.

External Integrator Webhooks

For inbound webhooks from third-party systems (payment gateways, 3DS providers, etc.) that call Eclipse APIs, a key-based authentication mechanism is available for scenarios where JWT generation is impractical.

See External Integrator Webhook Security for setup instructions.

Webhook Security

Outbound webhook requests from Eclipse can include an HMAC signature in the request headers to allow you to verify that the payload originated from Eclipse and has not been tampered with.

To enable HMAC signing:

  1. Set the HMACOutboundSignatureKey tenant config value to a secret key.
  2. Verify each incoming webhook by computing HMAC-SHA256(payload, key) and comparing to the Eclipse-Signature header in the request.

For inbound webhooks (where external systems call your Eclipse tenant), use HMACInboundSignatureKey and webhookAuthorizationHeader tenant config values.

See the Tenant Config Reference for all notification-related configuration keys.

Updated 19 days ago