Webhook

Learn how to listen to events whenever certain actions occur on your integration.

What are webhooks?

Whenever certain transaction actions occur on your Shoket integration, we trigger events that your application can listen to. This is where webhooks come in. A webhook is a URL on your server where we send payloads for such events. For example, if you implement webhooks, once payment is successful, we will immediately notify your server of a successful transaction event.

You can specify your webhook URL on your dashboard where we would send POST requests whenever an event occurs.

Here are things to note when setting up a webhook URL:

1. Do a test post to your URL and ensure the script gets the post body.

2. Ensure your webhook URL is publicly available (localhost URLs cannot receive events)

Receiving an event

All you have to do to receive the event is to create an unauthenticated POST route on your application. The event object is sent as JSON in the request body.

PHP

<?php
// Retrieve the request's body and parse it as JSON
$input = @file_get_contents("php://input");
$event = json_decode($input);
// Do something with $event
http_response_code(200); // PHP 5.4 or greater
?>

Node

// Using Express
app.post("/my/webhook/url", function(req, res) {
    // Retrieve the request's body
    var event = req.body;
    // Do something with event
    res.send(200);
});

Verifying events

It is important to verify that events originate from Shoket to avoid delivering value based on a counterfeit event.

You can do any or both of the below to verify events from Shoket:

1. Validate the Signature - Valid events are raised with an header Shoket-Signature which is essentially an HMAC SHA512 signature of the event payload signed using your secret key.

2. Watch the IPs - We only call your webhooks from these IP: 18.222.43.23

Responding to an event

You should respond to an event with a 200 OK. We consider this an acknowledgement by your application. If your application responds with any status outside of the 2xx range, we will consider it unacknowledged and thus, continue to send it. You don't need to send a request body or some other parameter as it would be discarded - we only pay attention to the status code.