Overview

Introduction

Webhooks enable real-time notifications for critical events in your organization's payment operations. Receive real-time updates when certain events occur, ensuring your systems stay synchronized with Mural account balance updates.

Creating Webhooks

Configure webhooks through the Mural API to receive HTTP POST requests when specific events occur:

1. Create the Webhook, which will create the Webhook in a DISABLED state. This will return a public key in PEM format that you can use to verify webhook event signatures coming from Mural.
2. Enable the Webhook by making a call to update the webhook with the status set to ACTIVE. This means that Mural will begin sending events to the registered Webhook.
3. Implement your endpoint and implement your webhook signature validation (see Signature Validation for more information)
4. Send a test event by making a call to the send event endpoint to test your integration.

Webhook Event Request Structure

The request body for every event sent by Mural will look like the following, where the eventCategory and corresponding payload types are defined by each event:

interface WebhookEventRequestBody {
  eventId: string;
  deliveryId: string;
  attemptNumber: number;
  eventCategory: MuralEventCategory;
  occurredAt: string; // ISO 8601 datetime
  payload: Payload;
}

For more information on the specific Payloads and MuralEventCategorys supported, see the Event Types page.

Headers

Every webhook event includes important headers for verification and tracking:

Delivery Guarantees

• Ordering: Events are delivered in the order they occur per Webhook-category pair
• Retries: Failed deliveries (non 200 http responses) are attempted a total of 3 times with exponential backoff for up to 6 minutes. 404 responses will result in immediate delivery failure with no retries.