Skip to main content
Webhooks let you receive real-time notifications when things happen in CharityStack. When a subscribed event occurs — a new donation, a subscription cancellation, a form update — CharityStack sends an HTTP POST request to a URL you specify, with a JSON payload describing the event. This lets you react immediately: update your CRM, trigger a thank-you email, sync records to an external database, or run any other workflow without polling the API.

​
The webhook object

The following fields are returned by GET /v1/webhooks and GET /v1/webhooks/{id}.
FieldTypeDescription
webhookIdstringUnique identifier for the webhook
urlstringThe destination URL that receives event payloads
eventsarray[string]List of event types this webhook is subscribed to
statusstringACTIVE, DISABLED, or DELETED
descriptionstringOptional label for your reference
createdAtintegerUnix timestamp when the webhook was created
lastDeliveryAtintegerUnix timestamp of the most recent delivery attempt
successCountintegerTotal number of successful deliveries
failureCountintegerTotal number of failed deliveries

​
Available events

Subscribe to any combination of the events below when you register a webhook.
EventTriggered when
donation.createdA new donation is received
donation.updatedA donation’s status changes
subscription.createdA new recurring subscription is started
subscription.updatedA subscription is modified (e.g., amount changed)
subscription.cancelledA subscription is cancelled
subscription.payment_method_updatedA subscription payment method is updated through a hosted update link
contact.createdA new donor contact is added
contact.updatedA contact’s information is updated
form.createdA new form is created
form.updatedA form’s configuration changes
When a hosted payment method update link completes, CharityStack emits subscription.payment_method_updated and also emits subscription.updated for backward compatibility. The dedicated payment method event includes a safe summary and excludes provider identifiers.

​
Registering a webhook

Call POST /v1/webhooks with a destination URL and the list of events you want to receive. 
curl -X POST https://0k90mc4jjj.execute-api.us-east-2.amazonaws.com/v1/webhooks \
  -H "Authorization: Bearer cs_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.example.com/charitystack-events",
    "events": ["donation.created", "subscription.cancelled"],
    "description": "Production event listener"
  }'
The webhook secret is included in the creation response and is never shown again. Copy it to a secure location — such as your environment variables or secrets manager — before closing the response. If you lose it, you must delete the webhook and create a new one.

​
Verifying webhook signatures

Every webhook delivery includes three headers that you should use to authenticate the request before processing the payload.
HeaderValue
X-Webhook-Signaturesha256=<hex_digest> — HMAC-SHA256 signature of the payload
X-Webhook-TimestampUnix timestamp of when the payload was signed
X-Webhook-IDUnique identifier for this delivery attempt
CharityStack signs each payload by combining the timestamp and raw request body, then computing an HMAC-SHA256 digest using your webhook secret. To verify a request:
1

Extract the headers

Read X-Webhook-Signature, X-Webhook-Timestamp, and X-Webhook-ID from the incoming request.
2

Construct the signed string

Concatenate the timestamp and the raw request body with a . separator:
{X-Webhook-Timestamp}.{raw_body}
3

Compute the expected signature

Compute an HMAC-SHA256 of the signed string using your webhook secret as the key, then hex-encode the result.
4

Compare signatures

Compare your computed digest to the value in X-Webhook-Signature (after stripping the sha256= prefix). Use a constant-time comparison to prevent timing attacks. Reject the request if they do not match.
5

Check the timestamp

Optionally reject requests where X-Webhook-Timestamp is older than a few minutes to protect against replay attacks.
The webhook verification guide includes ready-to-use code examples in multiple languages.

​
API endpoint

Create a webhook

Register a new webhook endpoint and subscribe to one or more event types.