System Outbound Webhooks

System Outbound Webhooks configure the HTTP endpoints that receive platform-wide event notifications from Payment Nexus. Use this page when an operations, automation, monitoring, or integration system needs to be notified about activity that can span multiple tenants.

System webhooks are different from tenant outbound webhooks. Tenant webhooks are configured inside a single brand and only report events for that brand. System webhooks are configured at the platform level and can receive events from across the whole Payment Nexus environment.

Permissions

Action	Permission required
View system webhooks	system:webhooks:read
Test a system webhook	system:webhooks:read
Add, edit, enable, disable, or delete system webhooks	system:webhooks:manage

Webhook table

The table lists every system webhook currently configured.

Column	Description
Description	An optional label explaining what the webhook is used for
Webhook URL	The HTTP or HTTPS endpoint that receives event notifications
Events	The event types this webhook is subscribed to
Enabled	Whether Payment Nexus should currently send events to this endpoint
Pre-Shared Key	The secret used to sign outgoing payloads, shown in masked form

Toolbar and row actions

Action	Description
Refresh	Reloads the webhook list from the backend
Add	Opens the form to create a new system webhook
Edit	Updates the webhook URL, description, events, enabled state, or pre-shared key
Test	Sends sample payloads for the webhook's subscribed events and reports whether the endpoint returned a successful response
Delete	Permanently removes the webhook

Adding or editing a webhook

The same fields are used when adding and editing a system webhook.

Field	Required	Description
Description	No	A short label that helps operators identify the webhook's purpose
Webhook URL	Yes	The HTTP or HTTPS endpoint that receives event notifications
Pre-Shared Key (PSK)	Yes	A shared secret used to verify that deliveries came from Payment Nexus
Events	Yes	One or more event types to send to this endpoint
Enabled	—	Controls whether Payment Nexus currently sends events to this webhook

WARNING

Changing the pre-shared key takes effect for future deliveries immediately. Coordinate key changes with the receiving system so it can verify new signatures before the webhook is relied on in production.

Available events

System webhooks can subscribe to account, configuration, operational, and payment events.

Event	Fires when
user.created	A user account is created
user.updated	A user account is updated
user.deleted	A user account is deleted
tenant.created	A tenant is created
tenant.updated	A tenant is updated
tenant.deleted	A tenant is deleted
psp.created	A payment service provider record is created
psp.updated	A payment service provider record is updated
psp.deleted	A payment service provider record is deleted
tenant_psp.created	A tenant-to-PSP assignment is created
tenant_psp.updated	A tenant-to-PSP assignment is updated
tenant_psp.deleted	A tenant-to-PSP assignment is deleted
role.created	A role is created
role.updated	A role is updated
role.deleted	A role is deleted
system.error	Payment Nexus records an unhandled system error
payment_intent_ticket.created	A payment intent ticket is created
payment_intent_ticket.updated	A payment intent ticket is updated
payment_intent_ticket.saved	A payment intent ticket is created or updated
payment_intent_ticket.canceled_to_succeeded_status_update_failed	A payment ticket was canceled locally but a later provider update indicated success, and Payment Nexus could not safely apply that status change automatically

Payload and signature verification

Each delivery is a POST request with a JSON body and these headers:

Header	Description
X-Request-ID	A unique UUID for this delivery
X-Event	The event type that triggered the delivery
X-Timestamp	ISO 8601 UTC timestamp of the delivery
X-Signature	A bcrypt hash for verifying authenticity
User-Agent	Payment Nexus/{VERSION} ({ENVIRONMENT})

To verify a delivery, reconstruct the pre-hash string {timestamp}|{psk}|{requestId}|{event} using the values from the headers and your stored PSK, then verify it against X-Signature using bcrypt. Checking the timestamp also helps guard against replay attacks.

The body uses this shared envelope:

{
  "requestId": "7c357b81-40c5-49f2-8826-38dfd40003eb",
  "event": "payment_intent_ticket.updated",
  "timestamp": "2026-05-25T12:00:00.000Z",
  "signature": "$2a$10$...",
  "data": {}
}

The contents of data depend on the event type.

Payment event tenant context

Payment-related system webhook payloads include both the tenant and the payment ticket. This allows receiving systems to identify which brand the event belongs to without needing to infer it from the ticket alone.

{
  "requestId": "7c357b81-40c5-49f2-8826-38dfd40003eb",
  "event": "payment_intent_ticket.canceled_to_succeeded_status_update_failed",
  "timestamp": "2026-05-25T12:00:00.000Z",
  "signature": "$2a$10$...",
  "data": {
    "tenant": {
      "id": 123,
      "name": "Example Brand"
    },
    "ticket": {
      "id": 456,
      "status": "canceled",
      "amount": {
        "value": "100.00",
        "currency": "USD"
      },
      "amountInBase": {
        "value": "90.00",
        "currency": "EUR"
      },
      "customer": {
        "eid": "crm-customer-id",
        "uid": 789
      },
      "meta": {
        "checkoutOrderId": "ORDER-123",
        "pspTxId": "provider-transaction-id",
        "pspTxInfo": null
      },
      "createdAt": "2026-05-25T11:30:00.000Z",
      "updatedAt": "2026-05-25T12:00:00.000Z"
    }
  }
}

TIP

If a receiving system routes events by brand, use data.tenant.id as the stable identifier and data.tenant.name as the human-readable label for logs, alerts, and dashboards.

Other event payloads

Lifecycle events such as user.created, tenant.updated, or role.deleted include the affected model name, record ID, and a diff summary in data.

System error events include error details such as name, code, message, stack, cause, metadata, and Sentry tags where available. These events are intended for operational alerting and incident investigation.

Testing a webhook

Use Test after creating or changing a webhook. The test action sends sample payloads for every event the webhook subscribes to and checks whether the receiving endpoint responds successfully.

For payment events, test payloads include sample tenant context:

{
  "tenant": {
    "id": 0,
    "name": "Test Tenant"
  }
}

Successful tests confirm that the endpoint is reachable and accepts the payload shape. They do not confirm that the receiving system performs all downstream business logic correctly.

Operational guidance

• Use narrow event subscriptions where possible so each receiving system only gets the events it needs.
• Keep disabled webhooks only when they are expected to be re-enabled; delete obsolete endpoints to reduce operational noise.
• Rotate pre-shared keys if an endpoint owner changes or a secret may have been exposed.
• Review outgoing webhook logs in Debug Tools — Webhooks when investigating delivery failures.