Receive Vote Notifications with Webhooks

FBL webhooks deliver real-time vote events to your server via HTTP POST requests, letting you reward voters instantly without polling the API.

Webhooks are the recommended way to react to votes in real time. When a user votes for your bot on FBL, FBL sends an HTTP POST request to a URL you specify. You process the payload and acknowledge receipt with a 2xx response. No polling required.

How webhooks work

A user votes for your project on FBL.
FBL sends an HTTP POST request to your configured webhook URL.
Your server processes the payload and returns a 2xx response within 5 seconds.

If your endpoint does not respond in time or returns a server error, FBL retries the delivery automatically.

Setting up your endpoint

Create an HTTP endpoint

Build an endpoint on your server that accepts POST requests and reads the raw request body. Your handler must return a 2xx status code to acknowledge each delivery.

Enter the webhook URL in your dashboard

Go to your bot's edit page on FBL and open the API tab. Paste the full URL of your endpoint (for example, https://your.bot/webhooks/votes) into the Webhook URL field.

Set an Authorization secret

Enter a shared secret in the Authorization field. FBL sends this value in the Authorization header of every webhook request so your endpoint can verify the request is from FBL.

Save and send a test

Save your changes, then click Send Test to deliver a test payload to your endpoint and confirm the handshake works end-to-end.

Signature verification

Every webhook request includes an HMAC signature header so you can verify the payload hasn't been tampered with. FBL sends these headers on every delivery:

Header	Description
`Authorization`	The exact secret you configured in the dashboard.
`X-FBL-Event`	The event name (`upvote` or `test`).
`X-FBL-Timestamp`	Milliseconds since epoch when the event fired.
`X-FBL-Signature`	`sha256=<hmac(timestamp + "." + body, secret)>` for replay protection.

Compare the signature to your own HMAC using the configured secret. Reject any request where the signature does not match or the timestamp is more than five minutes old.

Each request also includes an x-fbl-trace header containing a trace ID you can use when debugging delivery issues with FBL support.

Reliability

Always return a 2xx status code to acknowledge that you received the webhook. Returning any other status causes FBL to treat the delivery as failed and schedule a retry.

Property	Value
Timeout	5 seconds
Max retries	5
Retry delay	Exponential backoff: 2^N seconds (≈1s, 2s, 4s, 8s, 16s)
Retry triggers	Timeout or 5xx response

Authenticate with the FBL API

Webhook Event Reference for FBL