Delivery Monitoring

Monitor webhook delivery status and troubleshoot failures across all your tenant and merchant endpoints.

Delivery Log

Via Portal

Navigate to Webhooks > Delivery Log to view all webhook delivery attempts.

Each entry shows:

• Event type — e.g., payment.succeeded, merchant.created
• Endpoint — the target URL
• Status — current delivery state
• Response code — HTTP status returned by your server
• Timestamp — when the delivery attempt was made

Filtering

Filter the delivery log by:

• Status — delivered, failed, retrying, pending
• Endpoint — specific webhook URL
• Date range — narrow down to a time window
• Event type — specific event types

Delivery Statuses

Retry Behavior

When an endpoint returns a non-2xx response, Miracle retries with exponential backoff:

After all 9 retries (10 total attempts) are exhausted:

• The delivery is marked as failed.
• If an endpoint fails consistently across multiple events, it may be auto-disabled to prevent queue buildup.
• When an endpoint is auto-disabled, you receive a webhook.endpoint_disabled event on your other active endpoints.

To re-enable a disabled endpoint, update its status via the Portal or Admin API.

Troubleshooting

Failed Delivery

If deliveries are failing, check:

1. Endpoint URL — verify the URL is correct and publicly accessible.
2. SSL certificate — ensure the certificate is valid and not expired. Miracle requires HTTPS.
3. Server availability — confirm your server is running and accepting connections.
4. Firewall rules — allow inbound requests from Miracle's IP ranges.

Timeout

Miracle waits up to 10 seconds for your endpoint to respond. If your server takes longer:

• Return a 200 response immediately upon receiving the webhook.
• Process the event asynchronously in a background job.
• Use event.id for deduplication since the same event may be delivered more than once.

Signature Mismatch

If your verification is rejecting valid webhooks:

1. Verify the signing secret matches the one from endpoint creation or the most recent rotation.
2. Use the raw request body for HMAC computation — do not re-serialize the JSON.
3. Check the timestamp tolerance — reject only if the difference exceeds 5 minutes (300 seconds).
4. During secret rotation (24-hour grace period), both old and new secrets are valid. Your verification code should check against all v1 signatures in the header.

Missing Events

If you are not receiving expected events:

1. Confirm the event type is included in your endpoint's subscription list.
2. Check that the event is visible at the tenant level (see Tenant Event Catalog).
3. Verify the endpoint status is active (not disabled).