Webhooks

You can use the webhook-id header to check if you already processed a message. In case of a downtime or network issue, a message could be delivered more than once to ensure that you actually received them (reliability guarantee).

Flip updates the message timestamp in the webhook-timestamp header every time it attempts to deliver the message. The timestamp should never deviate more than a few minutes from your system time. If a timestamp is more than five minutes in the past or future, drop the message. It could be forged or an attempt at a replay attack. An authentic message will be re-delivered with an updated timestamp.

The webhook-signature header contains one or more base64-encoded HMAC-SHA256 signatures of the message content. If there is more than one signature, each is separated with a space character. A signature is prefixed with v1 to indicate that we currently use a symmetric encryption scheme. Use the Webhook API to obtain the shared secret used to sign the message. Shared secrets are prefixed whsec_ and base64-encoded. The signed content consists of the dot-separated webhook-id, webhook-timestamp, and the JSON-serialized payload (e.g. 9b3999bf-291b-44a3-a409-de1e247eb301.1730192335.{"items":[{"id":"283…).

Here is how we calculate the signature in Kotlin:

Here is an example of signed content:

84476261-219f-4f3c-9a3d-4184567c98dd.1745936362.{
  "id" : "84476261-219f-4f3c-9a3d-4184567c98dd",
  "items" : [ {
    "type" : "my.event.type",
    "data" : "SampleEvent123",
    "timestamp" : "2025-04-29T14:19:22.403Z"
  } ],
  "recipient" : "633e26c2-fa98-4773-8f35-e70dce70b6c5",
  "tenant" : "your-company"
}

With a key of whsec_VGhpcyBpcyBhIHNlY3JldCBrZXkgdXNlZCB0byBzaWduIHdlYmhvb2sgbWVzc2FnZXMh, the signature for this message is v1,lKU3+t3uPFkG8HCe3Z26GMvbY2/ecF/TG7BaDbil3Xc=.

The message body contains two additional fields:

• tenant contains the name of the Flip tenant for which the webhook was registered.
• recipient contains the Flip user ID of the API client that registered the webhook.

You can use these fields to validate requests or debug issues in multi-tenant integrations.

In general Webhook endpoints should react fast. Webhook messages can contain several hundred events and deliveries should not time out. We recommend receiving a message and putting the events in a local database or queue for subsequent processing.

Flip looks at the HTTP response code to decide if a message was delivered.

• Any 2xx response code means the message was successfully received by the subscriber.
• Any 5xx response means temporary failure and Flip will retry to deliver the same message multiple times.
• Any 4xx response is treated as an unrecoverable error and will pause the webhook.
• Any 3xx response is treated as an unrecoverable error and will pause the webhook.

Paused webhooks have to be reactivated via API call before they will resume delivery.

Only API clients can currently register webhooks. In general, webhooks can only receive events that are also visible to the subscribing API client (limited visibility). For example, an API client that is not a member of a group chat will not receive an event when a user sends a message to that group. We recommend to create API clients that are regular users instead of admins.

Some events do not or not yet have a natural receiver and are instead published to any subscribing webhook from the same tenant (global visibility). This applies, for example, to auditing events. Subscription to globally visible events will potentially give an API client broad access to data and should be considered carefully.