Webhooks SDK · For developers

Send events directly from your own code.

If your donation platform isn’t in our integrations list — or you’ve built your own — POST events straight to Cause Shield. One URL, free-form JSON, and an optional shared secret for authentication.

Get your webhook key →Or pick a platform

01 · Webhook URL

One endpoint per website.

Each website you create in Cause Shield gets a unique webhook_key. POST your events to:

URL pattern

POST https://causeshield.com/api/wh/{webhook_key}

Find your key in the dashboard under Website → Webhooks. The key alone identifies the website; it doesn’t need to be secret if you also use a shared secret (see authentication below). Successful requests return 204 No Content with an empty body — the response shape is intentionally identical for valid and invalid keys, so the endpoint can’t be probed via timing.

02 · Expected payload

Free-form JSON. The classifier figures it out.

The smart classifier accepts arbitrary JSON shapes — it’s designed to ingest envelopes from Funraisin, Raisely, and platforms you wrote yourself, without per-source mapping. You can also sendapplication/x-www-form-urlencoded or plain text; we’ll try to parse JSON out of it. A donation-shaped payload looks like:

JSON

{
  "event_type": "donation",
  "amount": 5000,
  "currency": "AUD",
  "email": "donor@example.org",
  "is_recurring": false
}

Amount is in minor units (cents). Email is hashed with a per-org pepper before storage; the original is never persisted. event_type is a hint — the classifier overrides it if the payload tells a different story.

03 · Authentication

Optional shared secret via Authorization: Bearer.

If you set a webhook_secret on the website, every inbound request must carry it as a bearer token:

HTTP header

Authorization: Bearer YOUR_WEBHOOK_SECRET

Requests without a matching token are silently dropped with a 204 — same response as an unknown webhook_key, so the endpoint stays unprobeable.

We don’t currently require HMAC signing — the bearer-token model keeps client code simple and matches what most donation platforms can send out of the box. If your platform only supports HMAC, get in touch and we’ll add a verifier on our side rather than asking you to change. Always send over HTTPS; we don’t accept plaintext webhook traffic.

Code examples

Pick your stack.

JavaScript (fetch)

// Node.js — POST a donation event to Cause Shield.
// The smart classifier accepts arbitrary JSON, so the only required
// thing is "send us something". Adding event_type / amount / currency
// makes the classification faster and more accurate.

const WEBHOOK_KEY = process.env.CAUSESHIELD_WEBHOOK_KEY
const WEBHOOK_SECRET = process.env.CAUSESHIELD_WEBHOOK_SECRET // optional

const payload = {
  event_type: 'donation',
  amount: 5000,         // in minor units (cents)
  currency: 'AUD',
  email: 'donor@example.org',
  is_recurring: false,
}

const res = await fetch(
  `https://causeshield.com/api/wh/${WEBHOOK_KEY}`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      // Only required if you set a webhook_secret on the website.
      ...(WEBHOOK_SECRET && { Authorization: `Bearer ${WEBHOOK_SECRET}` }),
    },
    body: JSON.stringify(payload),
  }
)

// 204 No Content on success. Body is always empty.
console.log(res.status)

Each example POSTs the same donation-shaped payload. Swap the event_type for registration, refund, dispute, or omit it entirely and let the classifier infer from the body.

Response + testing

What to expect after you POST.

Success

204 No Content, empty body

Every request that resolves to a valid website returns 204. Don’t parse the response body — there isn’t one. The event will appear in your dashboard within a few seconds, after the classifier runs.

Failure modes

Also 204 — by design

Unknown webhook_key, wrong bearer token, and rate-limit overruns all return 204 with no body. This prevents anyone from probing valid keys via response timing. Check your dashboard if you’re unsure whether events are landing.

Testing

Any successful POST shows up in your dashboard

The fastest way to verify wiring is to send a test event with curl from your laptop, then open your website’s Webhooks tab in the Cause Shield dashboard — the new event lands within a few seconds with the classifier’s event-type guess, risk score, and reasoning. The in-app webhook view also surfaces the last received timestamp and a rolling counter, so you can confirm production traffic is flowing without leaving the dashboard.

Wire your stack in an afternoon.

Start your 14-day trial →Ask us a question