Skip to main content
When a webhook delivery fails because Raise can’t reach your endpoint or your endpoint returns 503 Service Unavailable, Raise retries it a few times within about two minutes. Any other failure ends the delivery without a retry. This page covers the delivery rules, how to read retry history in the webhook logs, and the endpoint patterns that handle retries safely.

How Raise delivers and retries

Raise writes a webhook log entry for each attempt, so a retried delivery shows up as several log entries for the same contextId and eventId. Raise keeps the first 2 KB of your response body in the log’s serverResponse field. When a delivery fails for good, Raise doesn’t redeliver it later on its own. For a missed Gift_Added event, a Raise administrator can resend it, including straight from its webhook log entry. See Resending gift webhooks. For other events, run a reconciliation pass against the API.

The retry-from-the-partner-perspective view

You can observe retries through the webhook logs. Multiple log entries with the same contextId and eventId and different createdDate values are attempts of one delivery.

Inspecting retry history for a specific event

cURL
If multiple log entries return for the same gift, donor, or other resource ID, those are the retry attempts. The httpStatusCode and success fields show whether each attempt eventually succeeded.
JavaScript
For a delivery that succeeded on the first try, you’ll see one entry. For one that failed and was eventually retried successfully, you’ll see multiple entries — the earlier ones with non-2xx status codes and the later one with 2xx.

Listing only failed attempts

Add Success=false to either log list endpoint to return only failed attempts. Success=true returns only successful ones, and omitting it returns both. The total count and paging reflect the filter, and it combines with Filter.
cURL

Distinguishing “currently retrying” from “permanently failed”

All retries of a delivery happen within about two minutes of the first attempt. Read the log entries for an event like this: For integrations that need to know when an event was permanently lost, the most reliable signal is a periodic reconciliation check that compares expected events (from polling the underlying resources) against observed webhook deliveries. See Reconcile with CRM+: pattern 3 (periodic backstop).

How the partner endpoint controls retry behavior

Your endpoint’s HTTP response decides what Raise does next: The implication for partner endpoints: return the right status code for the situation.
  • If your endpoint received the request successfully and intends to process it, return 200 OK immediately. Don’t wait for processing to complete before responding.
  • If your endpoint can’t accept the request right now (rate limited, in maintenance, etc.), return 503 Service Unavailable. It’s the only status Raise retries, and the retries end within about two minutes, so plan to recover longer outages another way.
  • If the request is genuinely malformed (signature verification failed, body parsing failed), return 400 or 401. Raise won’t retry these.

Don’t return 200 for failures

A tempting anti-pattern: return 200 OK always, then log errors internally and hope someone notices. This breaks Raise’s retry mechanism — every delivery looks successful to Raise even when the partner actually failed to process it.
JavaScript
The correct pattern queues the event for processing and acknowledges receipt. The async processor — running outside the webhook handler — handles errors during actual processing, using its own retry and dead-letter mechanisms separate from the Raise retry mechanism.

Idempotency is non-negotiable

Because Raise retries failed deliveries, the same event can arrive at the partner endpoint more than once. The partner side must handle duplicates safely — without producing duplicate side effects. See Idempotency and Safe Reprocessing for the patterns. The summary:
  • Identify each event uniquely (typically by contextId + event type, or by a delivery ID if available).
  • Track already-processed events in a deduplication store.
  • Check the store before processing; skip if already processed.
  • Update the store after successful processing.
Without this, retries can produce double-charged donors (if your integration triggers payment flows), duplicate thank-you emails (annoying but not catastrophic), or doubled records in downstream systems (catastrophic for accounting).

Endpoint design that survives retries gracefully

A few patterns that make the partner endpoint robust against Raise’s retry behavior:

Acknowledge quickly

Return 200 OK within a few seconds. Raise gives each attempt 15 seconds, including reading your response. An endpoint that takes longer produces a retry even when the request is being handled correctly.
JavaScript
setImmediate (or equivalent in other frameworks) lets the response complete before processing begins.

Queue-based decoupling

A more robust pattern: use a message queue (SQS, Cloud Tasks, Redis-backed queue, etc.) between the webhook receiver and the event processor. Benefits:
  • The receiver is small and fast — it does only signature verification and enqueueing.
  • Processing failures are handled by the queue’s retry mechanism, not by relying on Raise to retry.
  • During traffic spikes, the queue absorbs load instead of overwhelming the processor.

Handle the timeout-but-succeeded edge case

A subtle issue: your endpoint processes the event successfully but is slow to respond. Raise times out, returns the delivery as failed, and retries. Your endpoint receives the same event a second time. Without idempotency, you’d process it twice. The defense:
  • Acknowledge quickly (as above) so timeouts are rare.
  • Implement idempotency (the next page) so duplicate processing is harmless when retries do occur.
These two defenses together produce a system that’s resilient to retries without depending on knowing the exact retry timing.

Investigating delivery problems

When the partner reports “we missed event X” or “we got the same event twice”:
1

Look up the webhook log entries for the event

Use GET /api/Webhook/{id}/log/list filtered to the relevant time range or context ID. Add Success=false to see only failed attempts.
2

Check the count of attempts

One entry = single successful delivery. Multiple entries = retries.
3

Check the response codes

2xx on the final attempt = Raise considers it delivered. Non-2xx on the latest = the delivery failed, unless the latest attempt is a 503 or no response from the last two minutes.
4

Inspect the response bodies

serverResponse shows what the partner endpoint returned. A 200 OK with an error message in the body is a partner-side processing issue, not a delivery issue.
5

Compare to expected events

If no log entries exist for an event you expected, the event may not have fired at all. Verify the underlying resource was actually created/updated in Raise.
The combination of webhook logs and the underlying resource records lets partner integrations triage most delivery issues without needing platform-team escalation. Save escalation for the cases where the logs show a permanent failure and the cause isn’t clear from the response.

Common scenarios

Scenario: partner endpoint was deployed during a maintenance window

If the partner endpoint was down for an hour during a deploy or outage, Raise retried each event that fired in that window for about two minutes and then stopped. Those deliveries failed. What to do:
  • List the failed deliveries during the outage window with Success=false.
  • For missed gifts, ask a Raise administrator to resend Gift_Added events for the date range, or to resend the failed log entries. See Resending gift webhooks.
  • For other events, run a reconciliation pass to catch the missed records and process them through your normal ingestion path.

Scenario: signature verification was broken in a deploy

If a partner deployment introduced a signature verification bug, every incoming webhook returned 401 Unauthorized. Raise doesn’t retry a 401, so each of those deliveries failed on the first attempt. What to do:
  • Fix the verification bug.
  • Run a reconciliation pass to catch all events that were rejected during the window.
  • Add an integration test for signature verification so this doesn’t recur.

Scenario: persistent 500 errors from the partner endpoint

The partner endpoint has been returning 500 Internal Server Error for an extended period. Raise doesn’t retry a 500, so every delivery in that period failed on its first attempt. What to do:
  • Identify and fix the root cause of the 5xx errors.
  • After the fix, run a reconciliation pass to catch missed events, or ask a Raise administrator to resend missed Gift_Added events.
  • If your endpoint can’t process events temporarily, return 503 instead of 500 so Raise retries.
  • Set up monitoring on the partner endpoint’s error rate to catch this faster next time.

Scenario: rate-limited at the partner endpoint

If the partner endpoint applies rate limiting and starts returning 429 Too Many Requests, Raise treats each 429 as a failed delivery and doesn’t retry it. What to do:
  • Raise the partner endpoint’s rate limit (this is a partner-side concern).
  • Or, add a buffering queue in front so the partner can absorb bursts without rate-limiting Raise.

Monitoring webhook delivery health

For partner integrations operating in production, two metrics are worth tracking: A periodic job can poll the webhook log endpoints and emit these as metrics:
JavaScript
Run this on a periodic cadence (every 5 minutes is a reasonable default) and alert on sustained drops in success rate.
The exact value of the success field (string "Yes", "True", boolean, etc.) is not documented in the spec. Inspect actual log entries to confirm the value, and adjust the metric calculation accordingly.

Where to go next

Idempotency and Safe Reprocessing

The companion pattern to retry handling — process duplicate deliveries safely.

Local Testing

Test the retry-and-acknowledge pattern locally before production.

Webhooks Overview

The full subscription lifecycle including log endpoint use.

Error Recovery Patterns

Broader patterns for handling failures across all of the partner integration.
Last modified on November 15, 2026