Overview

Why use webhooks

When building Flip integrations, you might want your applications to receive events as they occur in order to avoid polling Flip's endpoints, so that your backend systems can execute actions in real time.

To enable webhook events, you need to create a webhook endpoint in your system, and provide us with the URL. Flip uses HTTPS with the POST method to send webhook events to your app.

Destination

You can set the destination URL of the webhook via the Webhook configuration page of the developer portal.

Delivery status

Flip expects all webhooks to be acknowledged with a 204 No Content response. If a successful response is not received, our system will attempt two re-deliveries.

If your system becomes unresponsive (either times out or responds with error codes), the webhook delivery will be suspended and you will need to manually re-enable them to resume their delivery. As such, we recommend you set up monitoring of your webhook endpoint in order to quickly fix potential issues.

The default timeout period is 5 seconds.

Webhook payload

Webhooks will contain a JSON body, as documented here:

WebhookBody

event_type

string

required

event_object

object

required

Object schema depends on event type

The valid event types are documented here.

Best practices

Handle duplicate events

Webhook endpoints might occasionally receive the same event more than once. You can guard against duplicated event receipts by making your event processing idempotent. One way of doing this is logging the events you’ve processed, and then not processing already-logged events.

Handle events asynchrounously

Configure your handler to process incoming events with an asynchronous queue. You might encounter scalability issues if you choose to process events synchronously. Any large spike in webhook deliveries (for example, when a utility creates an event) might overwhelm your endpoint hosts.

Asynchronous queues allow you to process the concurrent events at a rate your system can support.

Best practices#

Best practices