Please note that this is an advanced feature for use by those comfortable with executing the necessary integrations.
Webhooks streamline data transfer via real-time delivery, improving app integration and facilitating communication between online services and platforms. A webhook is an HTTP request automatically triggered by an event (in Givebutter) and sent to a destination, along with information about the event (the request payload).
Usage example: When a new campaign is created (Event trigger) in your Givebutter account (source system), a notification (request payload) is sent to a specific Slack channel at your organization (destination, via a unique handler URL).
Available event triggers 🪝
campaign.created – Triggered when a campaign is created.
Resulting payload data
Resulting payload data
{
"event": "campaign.created",
"data": {
"id": 39,
"code": "ABCDEF",
"account_id": "ABCDEF",
"type": "collect",
"title": "My form",
"subtitle": null,
"description": null,
"slug": "ABCDEF",
"url": "https://givebutter.com/ABCDEF",
"goal": null,
"raised": 0,
"donors": 0,
"currency": "USD",
"cover": null,
"status": "active",
"timezone": "UTC",
"end_at": null,
"created_at": "2024-02-01T12:09:29+00:00",
"updated_at": "2024-02-01T12:09:29+00:00"
}
}
campaign.updated – Triggered when campaign details are updated.
Resulting payload data
Resulting payload data
{
"event": "campaign.updated",
"data": {
"id": 39,
"code": "ABCDEF",
"account_id": "ABCDEF",
"type": "collect",
"title": "My form",
"subtitle": null,
"description": null,
"slug": "ABCDEF",
"url": "http://givebutter.test/ABCDEF",
"goal": null,
"raised": 0,
"donors": 0,
"currency": "USD",
"cover": null,
"status": "active",
"timezone": "UTC",
"end_at": null,
"created_at": "2024-02-01T12:09:29+00:00",
"updated_at": "2024-02-01T12:09:34+00:00"
}
}
ticket.created – Triggered when a ticket is created. This refers to a supporter purchasing a ticket rather than creating a new ticket type in the dashboard.
Resulting payload data
Resulting payload data
{
"event": "ticket.created",
"data": {
"id": "72891263A0001",
"id_suffix": "A0001",
"transaction_id": "5aH2u32QUnl8hFVS",
"name": "John Doe",
"first_name": "John",
"last_name": "Doe",
"email": "[email protected]",
"phone": "+12674325019",
"title": "Ticket",
"description": "<p>Ticket</p>",
"price": 10,
"pdf": "https://givebutter.com/ticket.pdf",
"checked_in_at": null,
"created_at": "2024-02-01T12:18:01+00:00"
}
}
transaction.succeeded – Triggered when a transaction is successful. Does not fire during CSV imports.
Resulting payload data
Resulting payload data
{
"event": "transaction.succeeded",
"data": {
"id": "459oGBTylHk8laDF",
"campaign_id": 39,
"campaign_code": "ABCDEF",
"plan_id": null,
"team_id": null,
"member_id": null,
"fund_id": null,
"fund_code": null,
"first_name": "John",
"last_name": "Doe",
"company": null,
"email": "[email protected]",
"phone": "+12674325019",
"address": {
"address_1": "N 15th Ave",
"address_2": "123",
"city": "Melrose Park",
"state": "IL",
"country": "USA",
"zipcode": "60160"
},
"status": "succeeded",
"payment_method": "card",
"method": "card",
"amount": 250,
"fee": 7.78,
"fee_covered": 7.78,
"donated": 250,
"payout": 250,
"currency": "USD",
"transacted_at": "2024-02-01T12:15:20+00:00",
"created_at": "2024-02-01T12:15:20+00:00",
"giving_space": {
"id": 15,
"name": "John Doe",
"amount": 250,
"message": null
},
"dedication": null,
"transactions": [
{
"id": "2794514649",
"plan_id": null,
"amount": 250,
"fee": 7.78,
"fee_covered": 7.78,
"donated": 250,
"payout": 250,
"captured": true,
"captured_at": "2024-02-01T12:15:22+00:00",
"refunded": false,
"refunded_at": null,
"line_items": [
{
"type": "donation",
"subtype": "donation",
"description": "Donation to Recurring enabled",
"quantity": 1,
"price": 250,
"discount": 0,
"total": 250
},
{
"type": "donation",
"subtype": "fee",
"description": "Processing fee",
"quantity": 1,
"price": 7.78,
"discount": 0,
"total": 7.78
}
]
}
],
"custom_fields": [],
"utm_parameters": [],
"external_id": null,
"communication_opt_in": true,
"session_id": "945c8292-0b32-45ba-a4c4-9866fc15af07"
}
}
contact.created – Triggered when a new contact is created as the result of a new transaction or manual contact creation. Does not fire during CSV imports.
Resulting payload data
Resulting payload data
{
"event": "contact.created",
"data": {
"id": 89,
"prefix": null,
"first_name": "John",
"middle_name": null,
"last_name": "Doe",
"suffix": null,
"gender": null,
"dob": null,
"company": null,
"title": null,
"website_url": null,
"twitter_url": null,
"linkedin_url": null,
"facebook_url": null,
"emails": [],
"phones": [],
"primary_email": null,
"primary_phone": null,
"note": null,
"addresses": [],
"primary_address": null,
"stats": {
"total_contributions": 0,
"recurring_contributions": 0
},
"tags": [],
"custom_fields": [],
"external_ids": [],
"is_email_subscribed": false,
"is_phone_subscribed": false,
"is_address_subscribed": true,
"archived_at": null,
"created_at": "2024-02-01T12:13:22+00:00",
"updated_at": "2024-02-01T12:13:22+00:00"
}
}transaction.succeeded – Triggered when a transaction is successful. Does not fire during CSV imports.
Resulting payload data
Resulting payload data
{
"event": "transaction.succeeded",
"data": {
"id": "459oGBTylHk8laDF",
"campaign_id": 39,
"campaign_code": "ABCDEF",
"plan_id": null,
"team_id": null,
"member_id": null,
"fund_id": null,
"fund_code": null,
"first_name": "John",
"last_name": "Doe",
"company": null,
"email": "[email protected]",
"phone": "+12674325019",
"address": {
"address_1": "N 15th Ave",
"address_2": "123",
"city": "Melrose Park",
"state": "IL",
"country": "USA",
"zipcode": "60160"
},
"status": "succeeded",
"payment_method": "card",
"method": "card",
"amount": 250,
"fee": 7.78,
"fee_covered": 7.78,
"donated": 250,
"payout": 250,
"currency": "USD",
"transacted_at": "2024-02-01T12:15:20+00:00",
"created_at": "2024-02-01T12:15:20+00:00",
"giving_space": {
"id": 15,
"name": "John Doe",
"amount": 250,
"message": null
},
"dedication": null,
"transactions": [
{
"id": "2794514649",
"plan_id": null,
"amount": 250,
"fee": 7.78,
"fee_covered": 7.78,
"donated": 250,
"payout": 250,
"captured": true,
"captured_at": "2024-02-01T12:15:22+00:00",
"refunded": false,
"refunded_at": null,
"line_items": [
{
"type": "donation",
"subtype": "donation",
"description": "Donation to Recurring enabled",
"quantity": 1,
"price": 250,
"discount": 0,
"total": 250
},
{
"type": "donation",
"subtype": "fee",
"description": "Processing fee",
"quantity": 1,
"price": 7.78,
"discount": 0,
"total": 7.78
}
]
}
],
"custom_fields": [],
"utm_parameters": [],
"external_id": null,
"communication_opt_in": true,
"session_id": "945c8292-0b32-45ba-a4c4-9866fc15af07"
}
}
plan.canceled – Triggered when a plan is canceled.
plan.created – Triggered when a plan is created.
plan.resumed – Triggered when a plan is resumed.
plan.updated – Triggered when a plan is updated.
Custom field values 📝
Both the contact.created and transaction.succeeded event triggers include custom field information. If custom fields have a response/value, they will be formatted as follows.
"custom_fields": [
{
'id' => "identifier",
'field_id' => "identifier of the custom field",
'title' => "title of the custom field",
'description' => "description of the custom field",
'type' => "type of the custom field",
'value' => "value of the custom field response"
},
{
'id' => "identifier",
'field_id' => "identifier of the custom field",
'title' => "title of the custom field",
'description' => "description of the custom field",
'type' => "type of the custom field",
'value' => "value of the custom field response"
},
]
Create and edit webhooks ⚙️
In your Givebutter dashboard, navigate to Settings, then click on Integrations.
Select Webhooks from the sub-menu on the left side.
Click the New webhook button. A sidebar will open, where you can fill out the following fields for your new webhook:
Name (required)
Webhook URL (required) – The unique webhook handler URL destination where notifications are sent, typically an HTTPS link.
Events – Select which Events will trigger this webhook. You can select multiple options, but at least one is required.
Enable or Disable – New webhooks will be enabled by default.
Click Create at the bottom of the page when you're done.
To edit or delete a webhook, click the three dots [...] on the righthand side of the webhook. Click Edit to open up the sidebar to make changes, or click Delete to remove it.
Each time an event is triggered, an Event is added to the Activity feed for the relevant webhook. This includes the Status of the Event, as well as Created at and Updated at dates and times.
Click on an Event to expand it and view the webhook handler URL and Request data.
Authentication 🔒
A signing secret is a randomly generated string sent by Givebutter along with every webhook payload. This signature validates that the request is coming directly from Givebutter. Webhook URLs are open to the internet, so if a bad actor were to make a request that appears valid but doesn't include the correct signing secret, your server can reject the request as invalid. This is not required, but it is highly recommended.
Verifying a signing secret 👁
After a webhook is created in the dashboard, click the eye icon (View) next to the webhook you would like to verify. The resulting popup contains the signing secret for that particular webhook. The signature is unique for each webhook you've created.
Once you have the signing secret, review your code to see if the webhook request received contains a header called Signature. This should contain the same value in your dashboard.
FAQ 🤔
What is my webhook URL? What is my handler URL?
A webhook URL is the unique webhook handler URL destination where notifications are sent, typically an HTTPS link. They are often unique to your specific account (with the destination service) to ensure secure and targeted delivery of notifications. These will be formatted differently depending on your destination platform. For example, a Slack webhook URL will be formatted like this: https://hooks.slack.com/services/T00000000/B00000/XXXXXXXXX
Where can I find guides for specific platforms and apps?
Please note that these webhooks originate from Givebutter, so they will be considered incoming webhooks with regard to the destination service or platform.
Why should you verify webhook signatures?
Verifying a webhook signature ensures the notification truly comes from the intended platform and hasn't been tampered with. This safeguards your system from unauthorized access, data manipulation, and impersonation, making it crucial for secure and reliable webhook integrations.