Skip to main content
Registering a webhook tells CharityStack where to deliver event notifications. You specify a destination URL and the set of event types you want to receive. The response includes a one-time secret used to verify the HMAC-SHA256 signature on every delivery — save it immediately, as it cannot be retrieved again. This endpoint requires the webhooks:write permission.
The secret field is only included in this response and is never retrievable again. Store it securely in an environment variable or secrets manager before you proceed.

​
Request

POST https://0k90mc4jjj.execute-api.us-east-2.amazonaws.com/v1/webhooks

​
Headers

​
Authorization
string
required
Bearer token using your API key. Format: Bearer cs_live_your_key
​
Content-Type
string
required
Must be application/json.

​
Request body

​
url
string
required
The HTTPS URL that will receive webhook event payloads. HTTP is accepted in development environments only.
​
events
array[string]
required
One or more event types to subscribe to. The array must not be empty. Available values:
EventTriggered when
donation.createdA new donation is received
donation.updatedA donation’s status changes
subscription.createdA new recurring subscription starts
subscription.updatedA subscription is modified
subscription.cancelledA subscription is cancelled
subscription.payment_method_updatedA subscription payment method is updated through a hosted update link
contact.createdA new contact is added
contact.updatedA contact’s information is updated
form.createdA new donation form is created
form.updatedA form’s configuration changes
​
description
string
Optional human-readable label to help identify this webhook. Useful when you manage multiple endpoints.

​
Response

​
201 — created

​
webhookId
string
Unique identifier assigned to the new webhook.
​
url
string
The destination URL you provided.
​
events
array[string]
The event types you subscribed to.
​
status
string
Initial status of the webhook. Always ACTIVE on creation.
​
description
string
The description you provided, or an empty string if omitted.
​
createdAt
integer
Unix timestamp (seconds) when the webhook was registered.
​
lastDeliveryAt
integer
null on a newly created webhook — no deliveries have occurred yet.
​
successCount
integer
0 on creation.
​
failureCount
integer
0 on creation.
​
secret
string
HMAC-SHA256 signing secret for verifying webhook payloads. Shown only once. Use this value to validate the X-Webhook-Signature header on incoming deliveries.
​
warning
string
A reminder message confirming that the secret will not be shown again.

​
400 — bad request

Returned when required fields are missing, the url is not a valid HTTPS URL, or events is empty.

​
401 — unauthorized

Returned when your API key is missing, invalid, or lacks the webhooks:write permission.

​
Example

curl -X POST https://0k90mc4jjj.execute-api.us-east-2.amazonaws.com/v1/webhooks \
  -H "Authorization: Bearer cs_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/charitystack",
    "events": ["donation.created", "subscription.created", "subscription.payment_method_updated"],
    "description": "Production webhook for donation notifications"
  }'
Sample response (201)
{
  "webhookId": "wh_01hx4kz9mntd8vr2bpqe5ycf3a",
  "url": "https://yourapp.com/webhooks/charitystack",
  "events": [
    "donation.created",
    "subscription.created",
    "subscription.payment_method_updated"
  ],
  "status": "ACTIVE",
  "description": "Production webhook for donation notifications",
  "createdAt": 1714003200,
  "lastDeliveryAt": null,
  "successCount": 0,
  "failureCount": 0,
  "secret": "whsec_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
  "warning": "Save this secret now. You will not be able to see it again!"
}
After registering, verify your integration by sending a test event and confirming that your server correctly validates the X-Webhook-Signature header. See the webhook verification guide for implementation examples.