> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wegive.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> All nine organization webhook subscriptions, trigger behavior, and complete payload references.

WeGive offers **nine organization webhook subscription types**. This reference documents their triggers, request-body keys, signing, and delivery behavior. Browser events and data layers are covered separately in [Checkout Tracking](/external/onboarding/tracking).

<CardGroup cols={2}>
  <Card title="Receive and verify requests" icon="shield-check" color="#4d4a8c" href="/external/onboarding/webhooks/delivery">
    Headers, raw-body signature verification, retries, and dashboard test requests.
  </Card>

  <Card title="Checkout-session events" icon="workflow" color="#4d4a8c" href="/external/onboarding/webhooks/checkout-sessions">
    Complete session-created and session-completed envelopes and attribution keys.
  </Card>
</CardGroup>

## Webhook catalog

Action IDs are the integers used when configuring a subscription (`event_type`). **Actions 1–7 have no `event` name in their body and no `X-WeGive-Event` header.** Their human labels/constants below are not additional JSON fields. Use separate receiver URLs or your subscription configuration to identify them.

| Action | Subscription | Actual trigger | Body |
| - | - | - | - |
| 1 | New Donation (`NEW_DONATION`) | An organization-destination transaction is created and its status is not Failed (5). | Bare Donation object. |
| 2 | Updated Donation (`UPDATED_DONATION`) | An organization-destination transaction is updated and its resulting status is not Failed (5). | Same Donation object. |
| 3 | New Donor (`NEW_DONOR`) | **Currently both donor creation and donor update**, outside bulk-import mode. See the trigger details below. | Bare Donor object. |
| 4 | Updated Donor (`UPDATED_DONOR`) | Selectable and testable, but no normal donor model trigger uses action 4 in this documented version. | Donor shape if explicitly tested/triggered. |
| 5 | New or Updated Donor (`NEW_OR_UPDATED_DONOR`) | Donor creation/update outside bulk-import mode. | Same Donor object. |
| 6 | New or Updated Donation (`NEW_OR_UPDATED_DONATION`) | Both action-1 and action-2 conditions. | Same Donation object. |
| 7 | New or Updated Recurring Plan (`NEW_OR_UPDATED_RECURRING_PLAN`) | Organization-destination plan’s **saving** hook, before persistence. | Bare recurring-plan object including model attributes. |
| 8 | Checkout Session Created (`CHECKOUT_SESSION_CREATED`) | Checkout-session model created. | Envelope with `event: "checkout_session.created"`. |
| 9 | Checkout Session Completed (`CHECKOUT_SESSION_COMPLETED`) | First transition from both transaction/plan IDs null to at least one set. | Envelope with `event: "checkout_session.completed"`. |

## Trigger details that affect reporting

**Donation events (1, 2, 6):** “new” or “updated” does not mean paid. Pending, processing, refunded, disputed, and other non-failed statuses can be delivered. An update whose resulting status is Failed is excluded, so this catalog is not a complete failed-payment notification feed. These events are not limited to browser checkout gifts and can also represent renewals, imported/offline gifts, or other creation paths that run model events. Updates contain a snapshot, not a changed-field diff.

**Donor events (3, 4, 5):** the released `Donor::updated` implementation invokes actions 3 and 5, not 4. Treat action 3 as an upsert signal in this revision. Action 5 is the implemented create/update subscription. A successful dashboard test for action 4 proves receiver delivery only, not a working automatic update trigger. Donor webhooks are suppressed in bulk-import mode.

**Recurring-plan event (7):** this runs during `saving`, not after commit. It can occur on repeated/no-op saves. A new plan can have null `id`/timestamps and only currently assigned model attributes; a later database failure can occur after the HTTP call. Do not interpret every action-7 request as one newly persisted plan, or as a collected payment.

**Session created (8):** records creation of a session, normally when the checkout mounts; it is not proof of a distinct person or their first field edit. It applies across checkout configurations for the subscribed organization.

**Session completed (9):** correlates by the same session UUID. Repeated receipt updates do not normally create another completion event. Completion means a transaction or plan was attached; the trigger does **not** test transaction success status. A plan without an immediate charge also qualifies. The donor checkout’s receipt/session update supplies this linkage; if the donor leaves before that request, completion can be missing. There is no abandonment/expiry webhook in this catalog.

## Payload references

| Subscription family | Reference |
| - | - |
| Donations — actions 1, 2, 6 | [Donation payloads](/external/onboarding/webhooks/donations) |
| Donors — actions 3, 4, 5 | [Donor payloads](/external/onboarding/webhooks/donors) |
| Recurring plans — action 7 | [Recurring plan payloads](/external/onboarding/webhooks/recurring-plans) |
| Checkout sessions — actions 8, 9 | [Checkout session payloads](/external/onboarding/webhooks/checkout-sessions) |
| Related objects | [Nested object keys](/external/onboarding/webhooks/nested-objects) and [additional model attributes](/external/onboarding/webhooks/model-attributes) |
| Correlation and reporting | [Joining events & reporting](/external/onboarding/webhooks/reporting) |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.