Webhooks

Technical

The information on this page goes into technical detail, we recommend that you consult with your third party system integrator or support team for assistance.

Giant is not able to provide support for third party software, systems and webhook consumers.

Events

A webhook is sent to configured endpoints when a particular event occurs. The following types of events can trigger webhooks:

Payment

payment.pending

A payment has been created, but no money has yet been transferred anywhere.

payment.complete

A payment has been completed. Money has been transferred from the donor to the payment processor.

payment.failed

A payment was attempted, but it failed for some reason.

payment.refunded

A payment has been refunded, the receiving organisation no longer has access to the funds.

The Payment webhook payloads contain the following data:

{
    "webhook_endpoint_pk": "1",
    "event": "payment.complete",
    "app_label": "donations",
    "model_name": "Payment",
    "id": 9,
    "external_transaction_id": "test-123",
    "status": "COMPLETE",
    "amount": "100.00",
    "gift_aid": "None",
    "external_transaction_processing_fee": "3.93",
    "donation": {
        "donor": {
            "id": 9,
            "title": "Mr",
            "first_name": "Test",
            "last_name": "Person",
            "email": "[email protected]",
            "telephone_number": "00000000000",
            "address_line_one": "123 Test Street",
            "address_line_two": "Test Village",
            "address_city": "Test City",
            "address_region": "Test Region",
            "address_country": "Test Country",
            "address_postcode": "TEST 123",
            "can_claim_giftaid": false,
            "on_behalf_of": ""
        },
        "donor_message": "",
        "show_donor_name": false,
        "show_donation_amount": false,
        "is_paying_in_on_behalf_of": false,
        "is_thanks_email_sent": false,
        "is_organiser_email_sent": false,
        "custom_form_data": null,
        "payment_provider": "stripe",
        "is_recurring": false,
        "recurring_payment_status": "",
        "external_transaction_id": "test-123",
        "amount": "100.00",
        "created_at": "2023-10-09 12:59:25.240134+00:00",
        "updated_at": "2023-10-09 12:59:26.103246+00:00"
    },
    "campaign": {
        "id": 1,
        "name": "Example Campaign",
        "slug": "example-campaign-951ca",
        "active_from": "2023-07-13 16:04:05+00:00",
        "active_to": "None",
        "target_amount": "None",
        "amount_raised": "304.00"
    }
}

Adding an endpoint

Warning

For security reasons, we will only send webhook events to endpoints over an encrypted connection (HTTPS).

1. Log into your Giant Giving Dashboard and select "Webhooks" from the left menu.
2. Press "Create".
3. Enter the full url, including https:// into the endpoint box.
4. Select all of the events that you wish to receive webhooks for.
5. Press "Create".

You will be returned to the webhook listing page where you should see your new webhook configuration.

Tip

Take a note of the "token" as you will need this to verify that events you receive to your webhook endpoint were really created by Giant Giving.

Accepting incoming webhooks

Giant Giving will POST event webhooks to the configured HTTP endpoints. We use HMAC to allow you to verify that our system did indeed send the event, and that it has not been tampered with during transit.

The HMAC signature is provided in the HTTP_AUTHORIZATION header sent with every webhook request. Since every programming language has a different way to deal with HMACs, we cannot give specific guidance here, but we do provide an example for Python (note that this isn't complete code, you would need to get the signature from the HTTP header and add some more error handling)

import hashlib
import hmac
import json


 try:
    _, signature = signature.split(" ")
except ValueError as e:
    # Handle errors

data = request.body.decode("utf-8")
data = json.loads(data)

hmac_signature = hmac.new(
    bytes("YOUR_WEBHOOK_TOKEN_HERE", "utf-8"),
    bytes(data, "utf-8"),
    hashlib.sha256,
).hexdigest()

if not hmac.compare_digest(hmac_signature, signature):
    # Deal with incorrect HMAC here.

You should respond to the incoming webhook with a 200 HTTP status code (no body is required) so that Giant Giving knows you received and acknowledged the webhook. If you do not send a 200 status code, Giant Giving will assume that it has failed and will retry again each day, up to a maximum of 7 days.