How to Handle Webhook Requests

Creating a Webhook Endpoint

In order to receive webhook events, first you need to register an endpoint. From the Webhook Settings page, click the Add Webhook Event button and configure the following settings:

• Endpoint URL - This is the URL where Reflow will send requests with the webhook event data.
• Events - Select which event types you want to receive by checking the event you're interested in.

Endpoint settings can be changed at any time. If you need to update the URL or enable/disable events, click the Edit Endpoint option from the Webhook Settings page actions.

tip

Your project can have multiple endpoints registered at the same time. This can be useful if you want to receive events separately or try out different integrations.

Configure Webhook Backend

A webhook endpoint on your server works similarly to a regular webpage. It defines a publicly accessible URL route that listens for POST requests.

Many backend frameworks like Rails, Django and Laravel automatically check POST request for a valid CSRF token. Although this is an important security measure, routes that listen for webhook events should be exempt from CSRF protection.

Listen For Events

All Reflow events are sent in the form of an event object JSON. When your endpoint receives a new event, check the type property to know what kind of event has been received.

switch ($event->type) {

  case 'order.created':

    // Perform operations using the order data, like generating an invoice.

    $order = $event->data->object;

    $paidGross = $order->paid_gross;
    $discounts = $order->discounts;
    $taxes = $order->taxes;
    ...
    break;

  case 'user.created':

    // Perform operations on the new user, like sending a welcome email.

    $user = $event->data->object;

    $email = $user->email;
    $name = $user->name;
    ...
    break;

  default:
    error_log('Unknown event type');
}

One webhook endpoint can handle multiple different event types at once, or if you prefer you can set up individual endpoints for each type.

Delivery Attempts and Retries

For Reflow to consider the webhook exchange successful, it must receive a 2XX response in a reasonable amount of time.

If you need to execute complex code in the case of an event, it's advisable to first return a 200 response to avoid causing a timeout.

When your server returns a status different from 2XX or takes longer than 3 seconds to respond, Reflow will consider the event request as unsuccessful.

Automatic Retries

When an event request does not initially succeed, Reflow will attempt delivery 3 more times with increasing time intervals. The first retry is after a couple seconds and the last after several hours. Receiving a 2XX response on any attempt stops future tries.

Manual Retry

If you would like to manually resend an event, you can do so from the webhook endpoint dashboard by selecting the event and clicking the Resend button.

Send Test Events

While developing your webhook integration, it's advisable to use test webhook events. These can be sent from the endpoint dashboard by clicking the Send Test Event button and selecting the event type.

In the dashboard these events will be labeled with a Test badge to differentiate them from live production events.

Verifying Webhook Signatures

Reflow event requests have a header called Signature that contains a unique key for verifying the event integrity.

To verify event signatures, first go to the endpoint dashboard and copy the secret signing key (each endpoint has a different key).

Using the endpoint secret key, you can compute a signature string from the event payload and compare that to the Signature header. Here is how the signature is calculated (example in PHP):

// Get a signature string from the event payload and the endpoint signing key.

$signature = hash_hmac('sha256', json_encode($event), 'my_endpoint_signing_key');

// Compare the computed signature string to the Signature header.

if ($signature != $_SERVER['HTTP_SIGNATURE']) {
    http_response_code(400);
    exit();
}

Duplicate Events Handling

It is possible for an endpoint to receive the same event multiple times because of retries, a slow internet connection, or other rare circumstances.

The best way to avoid processing the same event more than once is to record the id (evt_...) of processed events and ignore those with an id that has already been recorded.

Order of Events

Although Reflow sends webhook events in a sequential order, we cannot guarantee the delivery order of events. For example, it's possible due to networking issues for an order.updated event to be received before the respective order.created event.