Webhooks

Updated on March 22nd, 2013

What's a Webhook?

A WebHook is an HTTP callback: an HTTP POST that occurs when something happens; a simple event-notification via HTTP POST.

Given.to's API uses webhooks to notify you of activity happening on your account outside of a direct API response. For example, when sending bulk purchase requests, our direct API response may be enough to verify that your bulk request has been received but our webhooks can notify you when those purchases have been completed.

Webhooks can also be useful in the unlikely event that a single purchase is unable to be completed in real-time. In this case, the direct API response will indicate that the request is "Pending", however, a webhook notification will be sent to your webhook url upon completion. Note: If for any reason a single purchase takes longer than 1 hour to complete, it will be cancelled and your account will not be charged. Webhooks will notify you of cancellations as well.

Receiving a webhook

To receive webhooks, enter a "Webhook URL" on the Webhook Settings page of your Given.to API Dashboard. Webhook data is sent as JSON in the body of the request.

To confirm that a webhook you've received is actually from Given.to, you can use the "request_id" sent in a webhook POST and request the remaining details directly from the request_lookup method of our API.

Responding to a webhook

To acknowledge that you've received the webhook successfully, your server should return a 200 HTTP status code. The request headers and request body will be ignored. Response codes other than 200, including 3xx codes, indicates to us that you did not receive the webhook. If we believe a webhook has not been received, Given will retry sending the webhook once an hour for up to 3 days.

Example

Receive data from a webhook

<?php

	// Retrieve the request's body and parse it as JSON
	$body = @file_get_contents('php://input');
	$event_json = json_decode($body);

	// Do something with $event_json

?>
				

Sample Webhook Data

{
	"event":"purchase_completed",
	"request_id":123456,
	"status":"SUCCESS",
	"date_received":"2013-01-01T04:59:58+0000",
	"campaign_id":"8910",
	"campaign_name":"Test Campaign",
	"api_method":"single_buy",
	"option":"send",
	"sent_format":"number",
	"sent_to":"5555555555",
	"app_id":"999921725",
	"app_name":"Test App",
	"sent":true,
	"date_sent":"2013-01-01T05:04:00+0000",
	"redeemed":false,
}