Skip to main content
Webhooks are under construction and are not stable yet. Do not rely on them in production. We will announce when webhook support is ready.
Webhooks notify your application when collateral, payment, or withdrawal state changes after the original request has finished. Unlike an API request where your application asks for current state, a webhook is event-driven. 4Mica sends an HTTP POST request to your configured endpoint when a subscribed event occurs. Use them for:
  • wallet and collateral dashboards;
  • payment reconciliation and entitlement updates;
  • withdrawal status notifications;
  • audit records and operational alerts.

​
Webhooks are asynchronous

Webhook delivery normally happens soon after an event, but it is not part of the synchronous transaction that produced the event. Delivery can be delayed, retried, duplicated, or arrive after another related event. Do not block a user-facing payment, deposit, or withdrawal flow while waiting for a webhook. Use the response from the original API or protocol operation for the immediate result, then use webhooks to reconcile and update your systems.
Never treat webhook delivery as guaranteed real-time confirmation. Your application must remain correct if an event is late or temporarily unavailable.

​
When to use webhooks

Webhooks work well when your application needs to:
  • update a database after a collateral or settlement change;
  • send a notification after a withdrawal changes state;
  • refresh a dashboard without polling continuously;
  • reconcile payment and delivery records;
  • trigger background accounting, analytics, or entitlement work.
Use a synchronous API response instead when the next step cannot continue without an immediate answer. Use a scheduled reconciliation job when missing an event would leave important records permanently stale.

​
How delivery works

  1. A subscribed 4Mica lifecycle event occurs.
  2. 4Mica creates an event with a unique id.
  3. 4Mica sends the JSON event to your HTTPS endpoint with an HTTP POST.
  4. Your endpoint verifies the signature against the raw request body.
  5. Your endpoint durably records or queues the event.
  6. Your endpoint returns a 2xx response.
  7. A worker applies the event to your application state.
Return a non-2xx response when you cannot durably accept the delivery. The sender may retry unsuccessful deliveries, so every handler must be idempotent.

​
Event envelope

Every event uses the same top-level shape:
​
id
string
required
Unique delivery identity used for deduplication.
​
type
string
required
Event name that determines the data shape.
​
created_at
string
required
ISO 8601 datetime
​
api_version
string
required
​
data
object
required
Event-specific payload.
Example event
{
  "id": "evt_01JY3K8F4TQ9M5C2N7A6B1D0EP",
  "type": "collateral.deposited",
  "created_at": "2026-06-22T14:30:00.000Z",
  "api_version": "2026-06-01",
  "data": {
    "user_address": "0x1111111111111111111111111111111111111111",
    "asset_address": "0x3333333333333333333333333333333333333333",
    "amount": "10000000",
    "network": "eip155:84532",
    "transaction_hash": "0xDepositTransaction",
    "block_number": 28123456,
    "status": "finalized"
  }
}
Treat every payload as untrusted until signature verification succeeds. After verification, still validate its type and required fields before processing.

​
Events

Collateral deposited

Refresh collateral after a finalized deposit.

Guarantee settled

Reconcile a guarantee that completed clearing and settlement.

Withdrawal requested

Show pending withdrawal and timing information.

Withdrawal finalized

Mark a withdrawal complete and refresh balances.

​
Syncing application data

Use webhook data to identify what changed, then fetch authoritative state when your application needs a complete or current record. This prevents a partial, late, or out-of-order event from overwriting newer data. A reliable database synchronization pattern is:
  1. Deduplicate the event by id.
  2. Find the local record using guarantee_id, withdrawal_id, or wallet address.
  3. Compare the incoming state with the local state.
  4. Fetch current API or protocol state if the transition is missing context.
  5. Apply the update in a database transaction.
  6. Record the event as processed.

​
Delivery failures and replay

Expect temporary failures from deployments, network issues, database outages, and handler bugs. Failed deliveries may be retried, but your application should not depend on a particular retry count or schedule. Keep enough information to replay an event safely from your own queue or dead-letter store. Replaying the same event must not apply the business change twice. Run scheduled reconciliation for high-value state such as collateral, guarantees, and finalized withdrawals. Webhooks reduce polling; they should not be the only recovery mechanism for financial records.

​
Next steps

Quick start

Build and test your first handler.

Security

Verify signatures and prevent replay.

Best practices

Handle retries, ordering, and observability.

FAQs

Find answers to common implementation questions.