Knowledge base | DonorShops.com

Webhooks

Webhooks allow you to build or set up GiveCloud Apps which subscribe to certain events on GiveCloud. When one of those events is triggered, we'll send a HTTP POST payload to the webhook's configured URL. Webhooks can be used to update an external CRM, trigger fulfillment services, or even update a backup. You're only limited by your imagination.

Once installed, they will be triggered each time one or more subscribed events occurs.

Events

When configuring a webhook, you can choose which events you would like to receive payloads for. You can even opt-in to all current and future events. Only subscribing to the specific events you plan on handling is useful for limiting the number of HTTP requests to your server. You can change the list of subscribed events through the API or UI anytime.

Each event corresponds to a certain set of actions that can happen to your shop and/or repository. For example, if you subscribe to the order_completed event you'll receive detailed payloads every time an order is completed.

Payloads

Each event type has a specific payload format with the relevant event information. All event payloads mirror the payloads for the Event types.

Delivery headers

HTTP requests made to your webhook's configured URL endpoint will contain several special headers:

HeadersDescription
X-GiveCloud-Event Name of the event that triggered this delivery.
X-GiveCloud-Signature HMAC hex digest of the payload, using the hook's secret as the key (if configured).
X-GiveCloud-Delivery Unique ID for this delivery.
X-GiveCloud-Domain Domain of the related to this delivery.

Also, the User-Agent for the requests will have the prefix GiveCloud-Hookshot/.

Example delivery

{
	"orders": [{
		"id": 2345,
		"order_number": "JDI8299323",
		"created_at": "2017-12-02 12:23:35 UTC",
		"updated_at": "2017-12-02 12:23:35 UTC",
		"test": false,
		"vendor_contact_id": 234, // << FROM DP
		"vendor_txn_ids": [1,2,4,5,6], // << FROM DP
		"subtotal_amount": "23.00",
		"shipping_amount": "0.00",
		"total_weight": 0,
		"total_tax": "0.00",
		"total_amount": "23.00",
		"currency": "USD",
		"processing_fee": "0.00",
		"refer_source": "Instagram",
		"order_source": "Web",
		"line_items": [{
			"id": 234,
			"variant_id": 23,
			"code": "",
			"name": "Coffee",
			"variant_title": "12oz Bag",
			"price": "7.00",
			"quantity": 2,
			"total": "14.00",
			"total_discount": "0.00",
			"promo": null,
			"weight": 23,
			"is_shippable": true,
			"fields": [{
				"id": 234,
				"name": "First Name",
				"value": "Josh"
			}]
		}],
		"billing_address": {
			"first_name": "",
			"last_name": "",
			"company": "",
			"email": "",
			"address1": "",
			"address2": "",
			"city": "",
			"state": "",
			"zip": "",
			"country": "",
			"phone": "",
		},
		"shipping_address": {
			"first_name": "",
			"last_name": "",
			"company": "",
			"email": "",
			"address1": "",
			"address2": "",
			"city": "",
			"state": "",
			"zip": "",
			"country": "",
			"phone": "",
		},
		"account": {
			"id": 234,
			"vendor_contact_id": 234, // << FROM DP
			"first_name": "Josh",
			"last_name": "Bloomfield",
			"email": "josh@jacie.ca",
			"type": "",
			"billing_address": {
				"first_name": "",
				"last_name": "",
				"company": "",
				"email": "",
				"address1": "",
				"address2": "",
				"city": "",
				"state": "",
				"zip": "",
				"country": "",
				"phone": "",
			},
			"shipping_address": {
				"first_name": "",
				"last_name": "",
				"company": "",
				"email": "",
				"address1": "",
				"address2": "",
				"city": "",
				"state": "",
				"zip": "",
				"country": "",
				"phone": "",
			},
			"memberships": [{
				"id": 234,
				"name": "Gold",
				"expires_on": "2017-03-01",
				"vendor_membership_id": "" // << FROM DP
			}]
		},
		"transactions": [{
			"gateway": "safesave",
			"transaction_id": "JISO9930DSG0",
			"transaction_type": "payment",
			"amount": "23.00",
			"cc_type": "Visa",
			"cc_number": "*************2342",
			"completed_at": "2017-12-02 12:23:35 UTC"
		}],
	}]
}