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 samecontextId and eventId and different createdDate values are attempts of one delivery.
Inspecting retry history for a specific event
cURL
httpStatusCode and success fields show whether each attempt eventually succeeded.
JavaScript
2xx status codes and the later one with 2xx.
Listing only failed attempts
AddSuccess=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 OKimmediately. 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
400or401. Raise won’t retry these.
Don’t return 200 for failures
A tempting anti-pattern: return200 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
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.
Endpoint design that survives retries gracefully
A few patterns that make the partner endpoint robust against Raise’s retry behavior:Acknowledge quickly
Return200 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.
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.
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_Addedevents 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 returned401 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 returning500 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
5xxerrors. - After the fix, run a reconciliation pass to catch missed events, or ask a Raise administrator to resend missed
Gift_Addedevents. - If your endpoint can’t process events temporarily, return
503instead of500so 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 returning429 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
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.