Skip to main content

Webhooks

webhook, webhooks, API, integration, send donations to my server, CRM sync, real-time donation notification, JSON payload, tokens, security header, bearer, refund event, recurring event, resend, developers

A webhook sends your donations to your own system (your CRM, database or app) automatically, shortly after each donation. You set it up yourself in your account, with no help needed from us.

Where to find it

Go to Settings › Sync › Webhook. If you don't see it, ask your account owner to give your user access to it.

What your webhook can send

One URL can receive five kinds of notifications. Every request has an event_type field, so your system can tell them apart.

Notification

event_type

When it is sent

New donation

donation

Every successful donation. Always on while the webhook is Active.

New recurring donation

recurring_started

The first successful charge of a new recurring donation, and when a stopped recurring donation is restarted.

Recurring donation stopped

recurring_stopped

Every time a recurring donation is stopped, with the reason.

Refund

refund

A donation is refunded. A refund is not sent as a new donation with a negative amount.

Failed donation not rescued

rescue

A donation failed and, 2 hours later, the donor has still not given successfully that day. These are the cases listed on Rescue My Donation.

The last four are switched on separately, under Other Events (see below).

Set up your webhook

  1. Enter your Webhook URL. It must start with https:// (or http://) and be reachable from the internet.

  2. Under Project, keep No Project (All) to receive every donation, or choose a project to receive only the donations to that project.

  3. Write the Payload Template (JSON): the JSON we send you, with tokens in curly braces where the donation details go. Click Load Example to start from a ready-made template. Click Add Token to insert a token where your cursor is.

  4. Click Validate JSON to check that the template is valid JSON and that every token is recognized.

  5. Make sure Active is on, and click Save Webhook.

  6. Click Test. We send your template, filled with sample values, to your URL, and show the HTTP status your server returned.

To stop all sending, switch Active off and save.

Example template

{
"event_type": "{event_type}",
"donation_id": "{donid}",
"transaction_id": "{trid}",
"amount": "{sum}",
"currency": "{currency}",
"frequency": "{frequency}",
"date": "{transaction_date}",
"project_id": "{projectid}",
"first_name": "{fname}",
"last_name": "{lname}",
"email": "{email}",
"phone": "{phone}",
"receipt_url": "{receipt_url}",
"custom1": "{cf1}"
}

Text tokens must be inside quotes, as above. Number and true/false tokens can be used with or without quotes. You can also use tokens in the URL, for example https://yoursite.com/webhook?donation={donid}.

How we send each request

  • POST to your URL, with your template (tokens replaced) as the body and Content-Type: application/json; charset=utf-8.

  • The header Authorization: Bearer <Security Header>. The Security Header is created the first time you save the webhook and is shown on the page. Check it on every request to make sure the request really comes from us, and keep it secret. It stays the same when you edit and save the webhook again.

  • Your server should answer with a 2xx status (for example 200). Any other status, or no answer, counts as a failure.

  • A failed request is sent again automatically a few more times. Meanwhile its status is Waiting for retry.

  • Because of retries and resends, the same donation can reach you more than once. Use donation_id to avoid saving it twice.

Tokens

Donation

{donid}

Donation number. In a refund event, the refund's own number.

{trid}

Payment transaction number

{sum}

Amount

{currency}

Currency

{frequency}

1 = one-time, 2 = monthly, 3 = yearly

{installments}

Number of installments

{transaction_date}

Date of the donation

{time_stamp}

Time the request was sent, as a Unix timestamp (UTC)

{approval_number}

Card approval number

{projectid}

Project ID (-1 when there is no project)

{campaignid}

Campaign ID

{campaignname}

The campaign page's name in its address (-1 when there is no campaign)

{routing_name}

Custom routing name, if the donation was routed

{processor_name}

Payment processor

{receipt_url}

Link to download the receipt

{igul_letova}

True when the donor joined Igul LaTova, otherwise False

{is_first_recurring_donation}

true for the first charge of a recurring donation

{is_first_donation_to_charity}

true when this is the donor's first donation to your organization

{cf1} … {cf10}

Custom fields 1 to 10 from your donation form

Donor

{donor_id}

Donor ID

{fname}, {lname}

First and last name

{email}, {phone}

Email and phone

{address}, {city}, {state}, {zipcode}

Address

{country}, {country_id}

Country name and country ID

{teudat_zeut_number}

Donor ID number, when the donor provided one

Events

{event_type}

donation, recurring_started, recurring_stopped, refund or rescue

{event_date}

When the event happened

{reason}

Why a recurring donation was stopped, or why a donation was refunded

{recurring_id}

The recurring donation's ID

{refund_amount}

Amount refunded

{refunded_donation_id}

Number of the donation that was refunded

{error_code}, {error_message}

Why the donation failed (rescue event)

Other Events

Once your webhook is saved, the Other Events section lets you choose which of the four extra notifications to receive. They go to the same URL with the same Security Header.

  1. Switch on Send this event for each event you want.

  2. Leave its Payload Template empty to receive the standard JSON: event_type, event_date, reason, recurring_id, refund_amount, refunded_donation_id, error_code, error_message and a donation object with the donation's details. Or write your own template: the event tokens and all the donation and donor tokens work.

  3. Click Save Events. You can test each event the same way as the webhook.

Check what was sent, and resend

Recent Webhook Calls shows the last 10 requests: the donation, its status, the error (if any), where it was added from, and when it was sent.

Pending

Waiting to be sent

Processing

Being sent now

Submitted

Your server accepted it

Waiting for retry

It failed and will be sent again automatically

Error

It failed. The Error column shows what your server answered.

Not sent

This donation was never sent to your webhook

To look up an older donation, enter its number under Find a donation and click Search. Click Resend to send a donation again. It is added to the queue and sent within a few minutes.

Troubleshooting

  • "Please save the webhook before testing": save first, then click Test.

  • "The webhook URL resolves to a disallowed (internal or local) address": the URL must be a public internet address, not localhost or an internal network address.

  • "The endpoint returned an error (HTTP …)": your server received the request and rejected it. Check your server's logs and the Security Header check.

  • A token arrives as text, for example {fname}: the token is misspelled. Click Validate JSON to find unrecognized tokens.

Prefer not to write code? Use our Zapier app to send donations to thousands of other apps.

Did this answer your question?