The webhook surface at a glance
The Raise webhook system has eight endpoints organized into two groups:Subscription management
Delivery logs
The log endpoints are one of Raise’s most useful diagnostic features. When a partner integration sees an event arrive (or fail to arrive), the logs show exactly what was delivered, what the partner’s endpoint responded with, and when. See Inspecting delivery logs below.
Creating a webhook subscription
cURL
The WebhookRequest fields
⚠️ Spec gap: The
format and status enums have two integer values each ([1, 2]) but the spec doesn’t label them. format: 1 likely corresponds to JSON delivery and format: 2 to an alternative format; status: 1 likely means active and status: 2 means inactive — but confirm against the live API before relying on these assumptions.Required fields in practice
The Raise spec doesn’t formally mark any WebhookRequest fields as required. In practice, however, all subscriptions need at least these four:name— for identifying the subscription in the admin UInotificationUrl— without it, events have nowhere to goeventTypesList— without it, no events match the subscriptionsecurityToken— required for signature verification (don’t deploy without it)
format and status fields can be omitted to use defaults, but explicit values are clearer.
Notification URL requirements
Raise only delivers to public HTTPS endpoints. When you create or update a webhook, Raise rejects anotificationUrl whose host is localhost, a *.internal or *.local name, or a private, loopback, link-local or other non-public IP address. The request returns 400 Bad Request with the error “NotificationUrl must point to a public internet host”.
Raise checks the address again when it delivers each event. If the host resolves to a non-public address, Raise doesn’t send the event, records the delivery as failed in the webhook log, and doesn’t retry it.
To test against a server on your own machine, expose it through a public HTTPS tunnel. See Local Testing.
Permissions
Managing webhooks requires edit access to the Account Settings role. Creating or updating a webhook also requires View access to the records its event types carry, because the webhook delivers those records:
Without that access,
POST /api/Webhook and PUT /api/Webhook/{id} return 403 Forbidden. The same check applies to reading a webhook’s delivery logs.
Storing the webhook ID
The create response includes the new subscription’sid. Store this — you’ll need it to update or delete the subscription later, and to fetch delivery logs for it.
JavaScript
The delivery model
When an event fires in Raise (a gift is created, a donor is updated, etc.), the platform identifies all webhook subscriptions whoseeventTypesList includes that event type and status is active. For each match, it makes an HTTP POST to the subscription’s notificationUrl with the event payload.
The HTTP request shape
The partner’s webhook endpoint receives a POST with:- A JSON (or alternative format, per the
formatfield) body containing the event payload. - A header carrying a signature derived from the
securityToken— used to verify the request came from Raise. See Signature Verification for the verification pattern. - An
X-RD-Event-Idheader with the event’s unique ID. The same value is in the payload’seventIdfield. - An
X-RD-Resend: trueheader when the delivery is a manual resend. See Resending gift webhooks.
- The event type identifier (the integer from the EventType enum)
- The resource that triggered the event (a Gift, Donor, RecurringGift, etc.) embedded in the payload
- Timing metadata (when the event occurred)
What the partner endpoint should do
The partner’s webhook endpoint should:1
Verify the signature
Use the
securityToken to verify the request actually came from Raise. Reject any request whose signature doesn’t validate — without this check, anyone who knows the URL can forge events. See Signature Verification.2
Acknowledge quickly
Return
200 OK as soon as the request is received and the signature is verified. Don’t process the event synchronously inside the request handler — queue it for processing and acknowledge.3
Process asynchronously
A background worker drains the queue and processes events. This decouples Raise’s delivery latency from your processing latency.
4
Handle duplicates
Webhook delivery is at-least-once, not exactly-once. Build the processor to handle duplicate deliveries gracefully — see Idempotency and Safe Reprocessing.
Delivery characteristics
A few things to know about Raise’s webhook delivery behavior:
See Retry Behavior for when Raise retries a delivery and the patterns to use on your endpoint.
Listing subscriptions
cURL
WebhookListModel:
The
statusDisplay and formatDisplay fields are useful for understanding the enum integers — status: 1 paired with statusDisplay: "Active" confirms the mapping. Inspect a few subscription records to learn the labels.
Updating a subscription
cURL
PUT /api/Webhook/{id} accepts the same body shape as create. Send the full record — the spec doesn’t expose a PATCH variant, so partial updates use the GET-then-PUT pattern.
Common update scenarios
Pausing vs. deleting
Usestatus: 2 to pause a subscription temporarily — useful during maintenance windows or partner-side issues. Use DELETE /api/Webhook/{id} to remove the subscription permanently when it’s no longer needed (e.g., during customer offboarding).
Deleting a subscription
cURL
notificationUrl. The subscription’s delivery logs may persist for a retention window — check via the log endpoints if needed.
Delete subscriptions during customer offboarding to stop sending events to a partner that’s no longer integrated. Leaving stale subscriptions in place wastes the customer’s notification budget and produces noise on the partner side if the URL is later reused.
Inspecting delivery logs
The webhook log endpoints are the diagnostic tool for investigating “the partner integration didn’t react to an event” issues. They show what Raise attempted to deliver and how the partner endpoint responded.Listing logs for a specific webhook
cURL
/list pagination parameters. SortBy accepts createddatetime, id, name (webhook name), eventtype, contextid, statuscode, success and modifieddatetimeutc. Rows that tie on the sort column are ordered by id in the same direction, so paging stays stable.
Listing only failed deliveries
Both log list endpoints accept an optionalSuccess query parameter. Success=false returns only failed deliveries, and Success=true returns only successful ones. Omit it to return both. The total count and paging reflect the filter, and it combines with Filter.
cURL
Searching logs
Both log list endpoints accept aFilter search term. To find every delivery for a gift, including manual resends, pass the gift ID:
cURL
- A number matches
contextId, the ID of the gift, donor or other record the delivery was for. A number from 100 to 599 also matcheshttpStatusCode. Any number also matches webhook names that contain it, so2024finds a webhook named “Integration 2024”. - Text matches the event type by its label or identifier (
Gift AddedorGift_Added, case-insensitive) and webhook names that contain the term.
id. To fetch one entry by its ID, use GET /api/Webhook/{id}/log/{logId}.
Filtering by date and time
Both log list endpoints accept an optional date range, read in the organization’s timezone:
If the organization has no timezone set, Raise uses your user timezone, then UTC. A range whose start is at or after its end returns
400 Bad Request with the message “From must be before To.” The range combines with Success and Filter, and total and paging reflect it.
cURL
createdDateTime. It shows each attempt in the same timezone the filter uses.
The WebhookLogListModel
Each log entry includes:
The
eventTypeDisplay field is the single best source of truth for the event type enum’s integer-to-label mapping. The spec doesn’t document the labels themselves, but inspecting delivery logs reveals them.
Investigating a missed event
A common diagnostic flow:1
Confirm the event fired
Query the webhook logs for the specific gift, donor, or other resource. If no log entry exists, the event wasn’t fired at all — investigate the source data.
2
Check the response status code
If
httpStatusCode is 2xx, Raise considers the delivery successful. The partner endpoint may have a bug in its processing pipeline rather than a delivery issue.3
Inspect the response body
serverResponse shows what the partner endpoint returned. A 200 OK with an error message in the body indicates a partner-side processing issue.4
Check for retries
Multiple log entries for the same
contextId indicate Raise retried delivery. The retry pattern can reveal whether the partner endpoint was intermittently failing.5
Fetch the full payload
Use
GET /api/Webhook/{id}/log/{logId} to get the singular log with payLoad — the full delivered body. Useful for confirming the exact data the partner endpoint received.Getting a single log’s full detail
cURL
WebhookLogModel with webhookName and payLoad — the full body delivered to the partner endpoint. Useful for confirming the exact shape of an event when building or debugging the partner-side handler.
Resending gift webhooks
When your endpoint was down for longer than Raise’s retries cover, a Raise administrator can resendGift_Added events to one webhook. A resend goes only to the selected webhook. Other webhooks subscribed to the same event receive nothing. Raise offers three ways to resend:
- One gift: from the gift’s details in Raise.
- Log entries: from a
Gift_Addedentry in the webhook log, or for several selected entries at once. Raise resends each entry to the webhook that logged it. A paused webhook must be reactivated first. - A date range: from the webhook settings in Raise, for every gift created in the range. Raise shows how many gifts match before you confirm, sends them oldest first and spaces them out so a recovering endpoint isn’t flooded. A paused webhook must be reactivated before you can resend to it.
Because a resend has a new
eventId, deduplicating on eventId alone processes a resent gift again. See Idempotency and Safe Reprocessing for a key that handles both.
Listing logs across all webhooks
cURL
/api/Webhook/{id}/log/list) is more targeted.
A complete subscription lifecycle
Putting the operations together as the full lifecycle for a customer onboarding:1
Generate a security token
Cryptographically random, at least 32 bytes. Store securely on the partner side; you’ll need it for signature verification on every delivery.
2
Create the subscription
POST /api/Webhook with the partner endpoint URL, the event type integers your integration cares about, and the security token.3
Store the webhook ID
Save the returned
id in your per-customer settings. You’ll need it for updates, deletes, and log queries.4
Deploy the receiver
Stand up the partner endpoint at the
notificationUrl. Implement signature verification before any event processing — see Signature Verification.5
Validate end-to-end
Run a test donation through the customer’s account (in test mode) and confirm the event arrives at the partner endpoint with a valid signature. Inspect the webhook logs to confirm Raise sent it and the partner returned
200 OK.6
Monitor in production
Watch the partner endpoint’s logs and the Raise webhook logs for signs of issues —
5xx responses on the partner side, signature failures, repeated retries.7
Update or pause as needed
During partner maintenance, set
status: 2 to pause delivery. During customer offboarding, DELETE /api/Webhook/{id} to remove permanently.Where to go next
Event Types
The catalog of available webhook events and the discovery pattern for the integer-to-label mapping.
Signature Verification
Verify that incoming requests actually came from Raise.
Retry Behavior
What Raise does when the partner endpoint doesn’t respond successfully.
Idempotency and Safe Reprocessing
Handle duplicate deliveries without producing duplicate side effects.