Skip to main content
Raise webhooks deliver real-time notifications when records change — donations completed, recurring schedules created or cancelled, donor updates, and others. For partner integrations that need to react to activity in Raise without polling, the webhook subscription is the canonical mechanism. This page covers the webhook subscription endpoints, the create/list/update/delete operations, and the diagnostic log endpoints that make webhook delivery investigations possible. The detailed event catalog is on Event Types; the request-validation pattern is on Signature Verification.

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 UI
  • notificationUrl — without it, events have nowhere to go
  • eventTypesList — without it, no events match the subscription
  • securityToken — required for signature verification (don’t deploy without it)
The 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 a notificationUrl 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’s id. 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 whose eventTypesList 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 format field) 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-Id header with the event’s unique ID. The same value is in the payload’s eventId field.
  • An X-RD-Resend: true header when the delivery is a manual resend. See Resending gift webhooks.
The exact body shape varies by event type. Most event payloads include:
  • 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)
For the full event-by-event payload reference, see Event Types.

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.
The “acknowledge quickly, process asynchronously” pattern is the single most important webhook practice. Endpoints that process synchronously inside the request handler hit timeouts under load and produce cascade failures during traffic spikes.

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
Returns the paginated list of webhook subscriptions for the organization. Each item is a 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

Use status: 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
Deletes the subscription permanently. Once deleted, no further events will be delivered to the previous 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
The endpoint supports the standard /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 optional Success 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 a Filter search term. To find every delivery for a gift, including manual resends, pass the gift ID:
cURL
Raise trims the term, then matches it like this:
  • A number matches contextId, the ID of the gift, donor or other record the delivery was for. A number from 100 to 599 also matches httpStatusCode. Any number also matches webhook names that contain it, so 2024 finds a webhook named “Integration 2024”.
  • Text matches the event type by its label or identifier (Gift Added or Gift_Added, case-insensitive) and webhook names that contain the term.
A number doesn’t match the log entry’s own 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
To match a window against the log entries, read 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
The single-log endpoint returns a 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 resend Gift_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_Added entry 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.
Resending requires the Account Settings role with edit access and View access to the Gifts, Donors, Reports role. A resent delivery differs from the original in these ways: 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
The org-wide log list — across every webhook subscription. Useful for the customer’s admin team to monitor delivery health across all integrations, or for investigating “are webhooks working in general” questions independent of a specific subscription. For per-integration diagnostics, the per-webhook log list (/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.
Last modified on November 17, 2026