Delivery and Retries

Understanding how Monime delivers webhooks helps you build reliable integrations. This page explains the delivery lifecycle, what constitutes a successful delivery, how retries work when things go wrong, and how to design your endpoint to handle the edge cases.

The delivery lifecycle

When an event occurs in your Space, Monime's webhook service begins the delivery process. The service matches the event against all active webhooks in the Space. For each webhook whose subscription includes that event type, Monime creates a delivery record.

The delivery record tracks the state of this particular attempt to notify your endpoint. It starts in a Pending state while Monime prepares the request. Monime then sends an HTTP POST request to your webhook's URL with the event payload in the body.

Your endpoint receives the request, processes it (or queues it for later processing), and returns an HTTP response. Monime reads the response status code to determine whether the delivery succeeded. If your endpoint returns a 2xx status code, Monime marks the delivery as Success and considers it complete.

If your endpoint returns a non-2xx status code, times out, or is unreachable, Monime marks the delivery attempt as failed. However, the delivery itself enters a Scheduled state, meaning Monime will retry. The delivery remains scheduled until either a retry succeeds or the retry window expires.

The HTTP request Monime sends

Each delivery is an HTTP POST request. Understanding its structure helps you parse and verify it correctly.

The request method is always POST. The Content-Type header is application/json, and the body contains the event payload as a UTF-8 encoded JSON object.

Monime includes a signature header that your endpoint uses for verification. Both HMAC-SHA256 and ECDSA P-256 webhooks use monime-signature with the same t=<timestamp>,v1=<base64-signature> value layout. Both methods sign timestamp_rawBody; only the signing and verification algorithm differs.

If you configured custom headers when creating the webhook, Monime includes those headers in every delivery. This lets you send authentication tokens or other metadata with each request.

The request looks like this:

POST /webhooks/monime HTTP/1.1
Host: api.example.com
Content-Type: application/json
monime-signature: t=1773386779,v1=eYpwGrKcNvG0PKXJBEZOYPLQfeUMZu6k+/klkPlL1y4=
Authorization: Bearer your-api-token  (if you configured this custom header)

{
  "apiVersion": "caph.2025-08-23",
  "event": {
    "id": "wke-7b3f2f1b5c1e4a",
    "name": "payment.processing_completed",
    "timestamp": "1760201200"
  },
  "object": {
    "id": "pay-4kL2n",
    "type": "payment"
  },
  "data": { ... }
}

What counts as a successful delivery

A delivery is successful when your endpoint returns any HTTP status code in the 2xx range. The most common choices are 200 OK and 202 Accepted.

Return 200 OK when you have fully processed the event before responding. This is the simplest approach for lightweight handlers.

Return 202 Accepted when you have received and queued the event but have not finished processing it. This is the recommended approach for handlers that perform slow operations like database writes, API calls to external services, or email sending. You acknowledge receipt immediately and process asynchronously.

Monime does not inspect the response body. You can return an empty body, a simple message, or JSON. The status code is what matters.

Any status code outside the 2xx range triggers a retry. This includes:

• 3xx redirects. Monime does not follow redirects because the redirect target might be unintended or untrusted. Return 2xx from the correct URL.
• 4xx client errors. These include 400 Bad Request, 401 Unauthorized, 403 Forbidden, and 404 Not Found. If your endpoint returns these codes, Monime assumes the request was rejected and retries in case the problem is transient.
• 5xx server errors. These include 500 Internal Server Error, 502 Bad Gateway, 503 Service Unavailable, and 504 Gateway Timeout. These indicate your server encountered a problem, and retrying later may succeed.

Timeouts

Monime waits a limited time for your endpoint to respond. If your endpoint does not return a response within this window, Monime treats the delivery as timed out, which counts as a failure and triggers a retry.

The exact timeout value is defined by Monime's backend configuration. Aim to respond within 5 seconds to stay safely under the limit.

If your handler does work that takes longer than a few seconds—like calling external APIs, processing images, or generating reports—change your architecture. Acknowledge the webhook immediately with a 202 response, store the event in a queue or database, and process it asynchronously in a background job. This pattern decouples receipt from processing and ensures your endpoint always responds quickly.

Retry behavior

When a delivery fails, Monime does not retry immediately. Instead, it schedules a retry with a delay. Subsequent retries use progressively longer delays, following an exponential backoff pattern. A typical schedule might be:

1. First retry after 1 minute
2. Second retry after 5 minutes
3. Third retry after 15 minutes
4. Fourth retry after 1 hour
5. Fifth retry after 6 hours
6. Final retry after 12 hours

The exact intervals and total retry count are determined by Monime's configuration and may vary. The key behavior is that retries spread out over time, giving your endpoint a chance to recover from transient issues without overwhelming it with requests.

Each retry sends the same payload as the original delivery. If your endpoint eventually succeeds, Monime marks the delivery as Success and stops retrying.

The retry window

Each delivery has a retry window that limits how long Monime will keep trying. After the retry window expires, Monime stops retrying and marks the delivery as Failed. The dashboard shows a "Retry Window Ends At" timestamp for each delivery so you know when retries will stop.

The retry window exists to prevent indefinite retry loops. If your endpoint is down for days, Monime eventually gives up so that stale events do not pile up.

When a delivery fails permanently, you can fix the underlying issue and then replay the delivery from the dashboard. Replaying creates a new delivery attempt using the original payload.

Delivery states

The Event Deliveries table in the dashboard shows one of these states for each delivery:

Pending means Monime has received the event and is about to send the first attempt. Deliveries are pending for only a few seconds under normal conditions.

Success means your endpoint returned a 2xx response. The delivery is complete, and no further attempts will be made.

Scheduled means the most recent attempt failed, but the retry window has not expired. Monime will retry according to the backoff schedule.

Failed means all retry attempts have been exhausted or the retry window has expired. Monime will not retry automatically. You can replay the delivery manually after fixing the issue.

Why deliveries fail

Failures fall into a few categories, each requiring a different response:

Your endpoint returned a non-2xx status code. Check your server logs to see why. Common causes include authentication failures (401), endpoint not found (404), validation errors (400), and unhandled exceptions (500).

Your endpoint timed out. Your handler took too long to respond. Optimize the handler or switch to asynchronous processing.

Your endpoint was unreachable. This could be a DNS failure, network partition, or firewall rule blocking Monime's requests. Verify your endpoint is accessible from the public internet.

TLS handshake failed. Your server's certificate may be expired, self-signed, or misconfigured. Use a valid certificate from a trusted certificate authority.

The delivery detail sheet in the dashboard shows the HTTP status code (if one was received) and may include additional failure metadata to help you diagnose the problem.

Designing for reliability

A robust webhook endpoint follows these principles:

Respond quickly, process later. Return 202 Accepted as soon as you have stored the event. Process it in a background worker that can retry, scale horizontally, and handle failures gracefully.

Handle duplicates. Retries mean the same event may arrive multiple times. Use the event ID to detect duplicates and skip re-processing.

Tolerate out-of-order delivery. If a delivery fails and is retried later, subsequent events for the same resource may arrive first. Design your logic to handle this, perhaps by checking timestamps or fetching the current state from the API.

Monitor continuously. Watch the Event Deliveries table and respond to failure alerts promptly. Unaddressed failures can cascade into data inconsistencies.

What happens after the retry window expires

When retries are exhausted and the delivery moves to Failed, Monime takes no further automatic action. The event notification is lost unless you intervene.

To recover, fix the issue that caused the failures, then replay the delivery from the dashboard. Replaying sends a new delivery attempt with the original payload. If your endpoint is now healthy, the replay succeeds.

If you cannot replay (for example, the delivery has been purged from the retention period), you can query the Monime API to fetch the current state of the resource and reconcile your system manually.

Alert emails

Monime sends email notifications when deliveries fail repeatedly. These alerts give you early warning that something is wrong. Configure alert emails when creating the webhook and ensure they reach people who can investigate.

Do not ignore alert emails. A few transient failures are normal, but persistent failures indicate a problem that will cause data loss if unaddressed.

Related topics

• Monitoring and debugging explains how to use the dashboard to investigate delivery issues.
• Testing locally covers how to test webhooks during development.
• Best practices provides architectural guidance for reliable integrations.