Webhook Management

As an operator, you can manage webhook endpoints at the tenant level to receive events across all your merchants. Tenant-level webhooks give you centralized visibility into payment activity, merchant lifecycle changes, and operational alerts without requiring each merchant to configure their own endpoints.

Tenant vs Merchant Webhooks

Miracle supports webhook endpoints at three levels, each with different data scope:

Key differences:

• Merchant endpoints receive merchant-visible data only (total fee amount, no fee decomposition, no provider details).
• Tenant endpoints receive enriched data including fee decomposition (providerFee, tenantFee, platformFee, partnerCommission), provider information, and routing details.
• Platform endpoints receive the full internal data representation.

Tenant endpoints also receive events that merchants cannot subscribe to, such as merchant.created, kyb.submitted, balance.negative, and routing/fraud alerts. See Tenant Event Catalog for the full list.

Managing Endpoints

Via Portal

1. Navigate to Settings > Webhooks
2. Click Create Endpoint
3. Provide:
   • URL — must be HTTPS
   • Events — select which event types to receive (or use wildcards like payment.*)
   • Description — optional label for your reference
4. Save. The signing secret is displayed once — copy and store it securely.

Via Admin API

POST /v1/admin/webhook-endpoints

{
  "url": "https://ops.example.com/webhooks",
  "events": ["payment.*", "merchant.*", "kyb.*"],
  "description": "Operations monitoring"
}

Response includes the secret field (shown only on create and rotate).

For full endpoint management (list, update, delete, rotate secret), see Admin API Reference.

Webhook Security

Tenant webhooks use the same Standard Webhooks signature scheme as merchant webhooks. Every delivery includes three headers:

Signatures are computed as HMAC-SHA256 over the signing base {webhook-id}.{webhook-timestamp}.{raw_body}, using your endpoint's signing secret (base64-decoded after stripping the whsec_ prefix). The result is base64-encoded and prefixed with v1,.

• Reject requests where the timestamp is more than 5 minutes old.
• During secret rotation, multiple signatures are sent — accept if any one matches.

For detailed verification steps and code examples in Node.js, Python, PHP, and Ruby, see the merchant webhook security docs.

Secret Rotation

Rotate your signing secret without downtime:

POST /v1/admin/webhook-endpoints/{endpoint_id}/rotate-secret

During the grace period (default 24 hours), both the old and new secrets are valid. The webhook-signature header includes signatures for both, so your verification code will match on either one.

Data Scoping

Tenant webhook payloads contain operator-level data. For payment events, this means you see:

• Full fee decomposition: providerFee, tenantFee, platformFee, partnerCommission
• Provider reference and provider status
• Routing decision details

This is more than what merchant endpoints receive (merchants see only the total merchantFee) but less than platform endpoints (which include all internal metadata).

Retry Policy

If your endpoint does not return a 2xx response within 10 seconds, Miracle retries the delivery with exponential backoff:

After all 10 attempts are exhausted, the delivery is marked as failed and a webhook.delivery_failed event is emitted. If an endpoint fails persistently, it may be auto-disabled (see webhook.endpoint_disabled in the Tenant Event Catalog).

Next Steps

• Tenant Event Catalog — full list of events available at the tenant level
• Delivery Monitoring — monitor delivery status and troubleshoot failures