Webhooks Overview

Webhooks push event notifications from Monime to your systems in real time. Instead of polling the API to check whether something has changed, you receive an HTTP POST request the moment an event occurs. This lets you build reactive systems that respond immediately to payments, payouts, checkout sessions, and other activities in your Space.

When webhooks solve the problem

Polling the Monime API works for some use cases, but it has drawbacks. You must choose a polling interval, which means either missing events (if the interval is too long) or wasting resources (if it is too short). Polling also adds latency between when an event occurs and when your system learns about it.

Webhooks eliminate these problems. Monime sends the event to your server within seconds of it occurring. You do not need to guess when to check or maintain polling infrastructure.

Use webhooks when you need to:

React to events in near real time. When a customer completes a payment, you can send a confirmation email, update inventory, or notify your fulfillment system immediately. When a payout fails, you can alert your finance team before they discover it the next morning.

Trigger downstream workflows. Events can start automated pipelines: create an invoice in your accounting system, update a customer record in your CRM, or log the event to an analytics platform.

Keep external systems synchronized. If you maintain a local database of payments or customers, webhooks let you update that database as changes happen in Monime. Your local data stays current without constant polling.

When webhooks are not the right choice

Webhooks deliver notifications asynchronously. If your workflow requires a synchronous response—where the result must be returned to the caller immediately—webhooks cannot help. For example, when you create a payment code and need to display the USSD string to the user on the same page load, use the API directly. The API call returns the response inline; a webhook would arrive too late.

Webhooks also require an endpoint that can accept inbound HTTPS POST requests. If you are building a mobile app without a backend, or if your server cannot accept incoming connections, webhooks will not work. In those cases, continue using API polling or consider adding a lightweight backend to receive webhooks.

How webhook delivery works

When an event occurs in your Space, Monime's webhook service matches the event against active webhook subscriptions. For each webhook that subscribes to that event type, Monime creates a delivery record and sends an HTTP POST request to the webhook's URL.

The request body contains a JSON payload describing the event. The payload includes metadata about the event itself—its unique ID, name, and timestamp—as well as a snapshot of the resource that triggered the event.

Your endpoint receives this request, processes it, and returns an HTTP response. Monime considers the delivery successful if your endpoint returns any 2xx status code. If your endpoint returns a non-2xx status code, times out, or is unreachable, Monime marks the delivery as failed and schedules a retry.

The following sequence illustrates the flow:

Event occurs in Space
        ↓
Webhook service matches event to subscriptions
        ↓
For each matching webhook:
    → Send HTTP POST with JSON payload
        ↓
    Your endpoint receives request
        ↓
    Verify signature
        ↓
    Process event
        ↓
    Return 2xx response
        ↓
Delivery marked successful

If your endpoint fails to respond correctly, Monime retries the delivery according to a backoff schedule. Retries continue until the delivery succeeds or the retry window expires. This ensures temporary outages do not cause permanent event loss, as long as your endpoint recovers in time.

Configuration options

When you create a webhook, you specify several configuration options that control its behavior.

The URL is the HTTPS endpoint where Monime sends deliveries. This must be a publicly reachable URL using a domain name. Monime does not send webhooks to localhost, private IP addresses, or plain HTTP endpoints.

The events you subscribe to determine which event types trigger this webhook. You can subscribe to one event, many events, or all available events. Subscribe only to the events your system needs; ignoring irrelevant events reduces noise and simplifies your handler.

The API release determines the payload schema. Monime versions its API through releases, and each release defines the structure of event payloads. When you select a release, the webhook receives payloads in that release's format. This allows your code to rely on stable field names and types.

The verification method controls how your endpoint proves that requests actually came from Monime. You choose between HMAC-SHA256, which uses a shared secret, and ECDSA P-256, which uses asymmetric cryptography. Both methods generate a signature that your endpoint verifies before processing the payload.

Alert emails specify who receives notifications when deliveries fail repeatedly. Monime sends these alerts so you know when your endpoint is unhealthy.

Custom headers let you include additional HTTP headers in every delivery. A common use case is adding an authentication token so your endpoint can verify requests at the network layer before signature verification.

Security model

Every webhook delivery includes a cryptographic signature. The signature proves that the request body has not been tampered with and that the request originated from Monime.

With HMAC-SHA256, Monime signs the timestamp, an underscore, and the raw request body using a secret known only to Monime and your server. The monime-signature header carries the timestamp and base64 signature. Your server reconstructs the same signed payload and compares the signatures.

With ECDSA P-256, Monime signs the same timestamp_rawBody payload using a private key that only Monime holds. The monime-signature header uses the same t=<timestamp>,v1=<base64-signature> layout as HMAC-SHA256. Your server reconstructs the payload and verifies the signature using the corresponding public key. Because only Monime has the private key, only Monime can produce valid signatures. This method also provides non-repudiation: you can prove to a third party that Monime sent a particular request.

Regardless of which method you choose, always verify signatures before processing the payload. An endpoint that processes unverified requests is vulnerable to forged events. An attacker who discovers your endpoint URL could send fake payment completion events, causing your system to ship products that were never paid for.

Access control

Webhooks are scoped to a Space. Users who can access the Developer section of a Space can create, view, modify, and delete webhooks within that Space. Users without developer access cannot see the Webhooks page.

Webhook secrets and public keys are visible only to users with appropriate permissions. Treat these credentials as sensitive. If a secret leaks, delete the compromised webhook and create a new one with a fresh secret.

Reliability considerations

Monime's webhook service is designed for reliability, but distributed systems involve trade-offs. Events can be delivered more than once due to retries, network errors, or replays. Your endpoint must handle duplicates gracefully, typically by tracking which event IDs have already been processed.

Events may arrive out of order. If a delivery fails and is retried later, subsequent events for the same resource may arrive first. Do not assume that events arrive in the sequence they occurred.

Monime retains delivery logs for a limited time. If you need a historical record of events, store them in your own system as you receive them.

Next steps

The following pages cover each aspect of webhooks in detail:

• Getting started walks through creating your first webhook and verifying it works.
• Creating webhooks explains each configuration field.
• Events and payloads documents the payload format and lists available events.
• Verification and security provides code examples for signature verification.
• Delivery and retries explains retry behavior and timeout handling.
• Best practices offers guidance for building reliable integrations.