Event Types

Account Balance Activity

Category	Payload Type	Description	Trigger
`mural_account_balance_activity`	`account_credited`	Funds received in a Mural account	Incoming blockchain transaction confirmed
`mural_account_balance_activity`	`account_debited`	Funds sent from a Mural account	Outgoing blockchain transaction confirmed

Account Credited and Debited Payloads

Account Credited

interface AccountCreditedPayload {
  type: 'account_credited';
  accountId: string;
  organizationId: string;
  transactionId: string; // this is the id that will appear in the Transactions API
  accountWalletAddress: string;
  tokenAmount: {
    blockchain: string;
    tokenAmount: number;
    tokenSymbol: string;
    tokenContractAddress: string;
  };
  transactionDetails: {
    blockchain: string;
    transactionDate: string; // ISO 8601 datetime
    transactionHash: string;
    sourceWalletAddress: string;
    destinationWalletAddress: string;
  };
}

Account Debited

interface AccountDebitedPayload {
  type: 'account_debited';
  accountId: string;
  organizationId: string;
  transactionId: string; // this is the id that will appear in the Transactions API
  accountWalletAddress: string;
  tokenAmount: {
    blockchain: string;
    tokenAmount: number;
    tokenSymbol: string;
    tokenContractAddress: string;
  };
  transactionDetails: {
    blockchain: string;
    transactionDate: string; // ISO 8601 datetime
    transactionHash: string;
    sourceWalletAddress: string;
    destinationWalletAddress: string;
  };
}

Payout Request

Category	Payload Type	Description	Trigger
`payout_request`	`payout_request_status_changed`	Payout request status has changed	Payout request transitions to a new status
`payout_request`	`payout_status_changed`	Individual payout status has changed	Fiat or blockchain payout transitions to a new status

Payout Request Status Changed Payload

This event is triggered when the overall payout request status changes. A payout request may contain multiple individual payouts (recipients).

interface PayoutRequestStatusChangedPayload {
  type: 'payout_request_status_changed';
  organizationId: string;
  payoutRequestId: string;
  statusChangeDetails: {
    previousStatus: PayoutRequestStatus;
    currentStatus: PayoutRequestStatus;
  };
}

// Status is an object with a type field (extensible for future properties)
type PayoutRequestStatus =
  | { type: 'awaitingExecution' } // Payout request created, awaiting blockchain execution
  | { type: 'pending' } // Blockchain transaction submitted, payouts in progress
  | { type: 'executed' } // All payouts completed successfully
  | { type: 'failed' } // One or more payouts failed
  | { type: 'canceled' }; // Payout request was canceled

Example Payload

{
  "type": "payout_request_status_changed",
  "organizationId": "org_abc123",
  "payoutRequestId": "pr_xyz789",
  "statusChangeDetails": {
    "previousStatus": { "type": "awaitingExecution" },
    "currentStatus": { "type": "pending" }
  }
}

Payout Status Changed Payload

This event is triggered when an individual payout's status changes. The statusChangeDetails object contains payout type and status information, where type indicates whether this is a fiat (bank transfer) or blockchain payout.

interface PayoutStatusChangedPayload {
  type: 'payout_status_changed';
  organizationId: string;
  payoutRequestId: string;
  payoutId: string;
  statusChangeDetails: FiatPayoutStatusChangeDetails | BlockchainPayoutStatusChangeDetails;
}

// Fiat payout status change details (bank transfers)
interface FiatPayoutStatusChangeDetails {
  type: 'fiat';
  previousStatus: FiatPayoutStatus;
  currentStatus: FiatPayoutStatus;
}

// Blockchain payout status change details
interface BlockchainPayoutStatusChangeDetails {
  type: 'blockchain';
  previousStatus: BlockchainPayoutStatus;
  currentStatus: BlockchainPayoutStatus;
}

// Fiat payout statuses - objects with type field
type FiatPayoutStatus =
  | { type: 'created' } // Payout created, awaiting processing
  | { type: 'pending' } // Payout submitted to provider
  | { type: 'onHold' } // Payout on hold (compliance review)
  | { type: 'completed' } // Funds delivered successfully
  | { type: 'failed' } // Payout failed
  | { type: 'canceled' } // Payout was canceled
  | { type: 'refundInProgress' } // Refund is being processed
  | { type: 'refunded' }; // Funds refunded to source account

// Blockchain payout statuses - objects with type field
type BlockchainPayoutStatus =
  | { type: 'awaitingExecution' } // Awaiting blockchain transaction
  | { type: 'pending' } // Transaction submitted to blockchain
  | { type: 'executed' } // Transaction confirmed on blockchain
  | { type: 'failed' } // Transaction failed
  | { type: 'canceled' }; // Payout was canceled

Example Fiat Payout Payload

{
  "type": "payout_status_changed",
  "organizationId": "org_abc123",
  "payoutRequestId": "pr_xyz789",
  "payoutId": "payout_def456",
  "statusChangeDetails": {
    "type": "fiat",
    "previousStatus": { "type": "created" },
    "currentStatus": { "type": "pending" }
  }
}

Example Blockchain Payout Payload

{
  "type": "payout_status_changed",
  "organizationId": "org_abc123",
  "payoutRequestId": "pr_xyz789",
  "payoutId": "payout_ghi012",
  "statusChangeDetails": {
    "type": "blockchain",
    "previousStatus": { "type": "pending" },
    "currentStatus": { "type": "executed" }
  }
}

Business Verification

Category	Payload Type	Description	Trigger
`business_verification`	`verification_status_changed`	Business verification status has been updated	KYC/KYB review completed or status change occurred

Verification Status Changed Payload

interface BusinessVerificationStatusChangedPayload {
  type: 'verification_status_changed';
  organizationId: string;
  previousStatus: MuralKycVerificationStatus;
  currentStatus: MuralKycVerificationStatus;
  verificationId: string;
  updatedAt: string; // ISO 8601 datetime
}

// Status objects returned based on verification state
type MuralKycVerificationStatus =
  | { type: 'inactive' }
  | { type: 'pending' }
  | { type: 'approved'; approvedAt: string }
  | { type: 'errored'; details: string; erroredAt: string }
  | { type: 'rejected'; reason: string; rejectedAt: string };

Example Status Objects

Inactive Status:

{ "type": "inactive" }

Pending Status:

{ "type": "pending" }

Approved Status:

{
  "type": "approved",
  "approvedAt": "2024-03-21T10:30:00Z"
}

Errored Status:

{
  "type": "errored",
  "details": "Verification encountered an error",
  "erroredAt": "2024-03-21T10:30:00Z"
}

Rejected Status:

{
  "type": "rejected",
  "reason": "Verification was rejected",
  "rejectedAt": "2024-03-21T10:30:00Z"
}

Organization Terms of Service

Category	Payload Type	Description	Trigger
`organization_tos`	`tos_accepted`	Organization accepted Terms of Service	Initial TOS acceptance by organization

TOS Accepted Payload

interface OrganizationTosAcceptedPayload {
  type: 'tos_accepted';
  organizationId: string;
  signedAt: string; // ISO 8601 datetime
  source: 'ui' | 'api' | 'test';
}

Source Field Values

ui: TOS was accepted through the Mural web application by an authenticated user
api: TOS was accepted via the public REST API endpoint
test: TOS event was triggered as a test webhook

Example Payload

{
  "type": "tos_accepted",
  "organizationId": "org_abc123",
  "signedAt": "2024-03-21T10:30:00Z",
  "source": "ui"
}

Note: This event is only sent on initial TOS acceptance. Re-signing or updating agreements will not trigger additional webhook events.