API
Webhooks
Receive signed events, and manage the endpoints they are sent to and each delivery.
A webhook endpoint is an https address on the public internet that Flipbird sends events to, such as document.processed or invoice.paid. A workspace has up to 10. Endpoints are added, and their secrets made and rotated, in the workspace under Settings, Webhooks; the API lists, changes, turns off and removes them, and follows and resends their deliveries.
Each event becomes one delivery per active endpoint subscribed to its type. A delivery is pending, then delivering, then succeeded when the endpoint answers 2xx, or dead after 8 failed attempts. webhookDeliveries.dead lists dead deliveries across every endpoint, and webhookDeliveries.redeliver sends a finished delivery again from its first attempt, with the same webhook-id. These routes need settings.manage.
Setting up an endpoint
An Owner or Admin adds endpoints under Settings, Webhooks, choosing the events each receives. Its signing secret, whsec_…, is shown once, when the endpoint is made or its secret rotated. The API reads, changes and removes endpoints; adding one and rotating its secret happen in the workspace.
- The address must be https, on port 443, on the public internet.
- A workspace may have at most 10 endpoints.
- An endpoint that receives
form.submittedmust be set up by a member or key holdingdocuments.publish.manage: it carries readers' answers from every document.
Events
| Event | When it is sent |
|---|---|
document.processed | An engine job on a document's version finished, or failed after its last attempt. A new upload's processing raises one per job; error is present only on a failure, with a stable code and a sentence for people. |
export.completed | An export finished and is ready to download, in addition to its document.processed. Download it with the exports routes; file, contentType and bytes describe the file. |
invoice.paid | A subscription invoice was paid. Amounts are in the currency's smallest unit (cents for USD). |
credits.low | The credit balance crossed a mark this month: low, empty (at or below zero) or throttled (metered work paused). Sent once per mark per calendar month. |
link.clicked | Visits to the workspace's short links and QR codes, in a batch: at most one event an hour, covering from (inclusive) to to (exclusive), never more than the last 24 hours. Bots are excluded, and only visits the workspace records count. A window with no visits sends nothing. links lists the most visited first, at most 500; truncated says more had visits. |
invoice.payment_failed | A subscription invoice could not be collected. Sent once per attempt: attempt is 1 for the first failure. nextAttemptAt is null when no retry is scheduled. |
form.submitted | A reader sent a publication's lead form. It carries what they typed into the fields the form asked for, and nothing about their connection. Sent once per submission. An endpoint subscribed to it must be set up by a member or key that holds documents.publish.manage. |
Each delivery's body is the event: its id, type, createdAt (epoch milliseconds), the workspace's tenantId, and the event's data.
document.processed
{
"id": "evt_1r5t6wnb7m2kq9vx4c8d",
"type": "document.processed",
"createdAt": 1767225600000,
"tenantId": "ten_wnb7m2kq9vx4c8d1r5t6",
"data": {
"documentId": "doc_7m2kq9vx4c8d1r5t6wnb",
"version": 3,
"job": {
"id": "job_4c8d1r5t6wnb7m2kq9vx",
"type": "viewer-pages",
"status": "done"
},
"pages": 24
}
} export.completed
{
"id": "evt_1r5t6wnb7m2kq9vx4c8d",
"type": "export.completed",
"createdAt": 1767225600000,
"tenantId": "ten_wnb7m2kq9vx4c8d1r5t6",
"data": {
"documentId": "doc_7m2kq9vx4c8d1r5t6wnb",
"version": 3,
"export": {
"id": "job_9vx4c8d1r5t6wnb7m2kq",
"type": "export-offline",
"file": "export.zip",
"contentType": "application/zip",
"bytes": 18874368
}
}
} invoice.paid
{
"id": "evt_1r5t6wnb7m2kq9vx4c8d",
"type": "invoice.paid",
"createdAt": 1767225600000,
"tenantId": "ten_wnb7m2kq9vx4c8d1r5t6",
"data": {
"invoiceId": "in_1QxYz2AbCdEfGhIj",
"subscriptionId": "sub_1QxYz2AbCdEfGhIj",
"amountPaid": 4900,
"currency": "usd"
}
} credits.low
{
"id": "evt_1r5t6wnb7m2kq9vx4c8d",
"type": "credits.low",
"createdAt": 1767225600000,
"tenantId": "ten_wnb7m2kq9vx4c8d1r5t6",
"data": {
"standing": "low",
"balance": 120
}
} link.clicked
{
"id": "evt_1r5t6wnb7m2kq9vx4c8d",
"type": "link.clicked",
"createdAt": 1767225600000,
"tenantId": "ten_wnb7m2kq9vx4c8d1r5t6",
"data": {
"from": 1767222000000,
"to": 1767225600000,
"clicks": 42,
"links": [
{
"linkId": "lnk_2kq9vx4c8d1r5t6wnb7m",
"code": "spring26",
"kind": "qr",
"clicks": 30
},
{
"linkId": "lnk_8d1r5t6wnb7m2kq9vx4c",
"code": "a7Kp2Q",
"kind": "link",
"clicks": 12
}
],
"truncated": false
}
} invoice.payment_failed
{
"id": "evt_1r5t6wnb7m2kq9vx4c8d",
"type": "invoice.payment_failed",
"createdAt": 1767225600000,
"tenantId": "ten_wnb7m2kq9vx4c8d1r5t6",
"data": {
"invoiceId": "in_1QxYz2AbCdEfGhIj",
"subscriptionId": "sub_1QxYz2AbCdEfGhIj",
"attempt": 1,
"amountDue": 4900,
"currency": "usd",
"nextAttemptAt": 1767484800000
}
} form.submitted
{
"id": "evt_1r5t6wnb7m2kq9vx4c8d",
"type": "form.submitted",
"createdAt": 1767225600000,
"tenantId": "ten_wnb7m2kq9vx4c8d1r5t6",
"data": {
"documentId": "doc_7m2kq9vx4c8d1r5t6wnb",
"publicId": "k3m9x2p7q4v8w1z5",
"lead": {
"id": "led_5t6wnb7m2kq9vx4c8d1r",
"documentId": "doc_7m2kq9vx4c8d1r5t6wnb",
"name": "Alex Example",
"email": "alex@example.com",
"company": "Example Pty Ltd",
"phone": null,
"custom": {
"label": "What are you shopping for?",
"answer": "Outdoor furniture"
},
"consent": {
"given": true,
"text": "Send me news and offers.",
"privacyUrl": "https://example.com/privacy"
},
"gate": "open",
"embed": false,
"submittedAt": 1767225000000
}
}
} Delivery and retries
Each event is a POST of JSON to the endpoint. Answer with any 2xx within 10 seconds to acknowledge it; do slow work after answering. A redirect, another status, or no answer in time is a failure.
| Header | Holds |
|---|---|
webhook-id | The event's id, the same on every attempt. Deliveries can arrive more than once and out of order: use it to ignore one you have handled. |
webhook-timestamp | Seconds since the epoch, when this attempt was signed. |
webhook-signature | v1, and the base64 signature; several, space-separated, while a rotated secret still signs. |
user-agent | Starts Flipbird-Webhooks/1. |
A failed attempt is tried again after 30 seconds, then 1.5 minutes, then 4.5 minutes, then 13.5 minutes, then 40.5 minutes, then 2 hours, then 6.1 hours: 8 attempts over about 9.1 hours. Then the delivery is dead: it is listed by the dead-letter endpoint below, and sent again only when you redeliver it. Events and their deliveries are kept for 30 days.
Verifying signatures
Deliveries are signed in the Standard Webhooks scheme, so its libraries for most languages verify them. The signature is an HMAC-SHA256, under the bytes the secret's base64 (after whsec_) decodes to, of the event id, the timestamp and the raw body joined by full stops. Check it against the body exactly as received, before parsing it, and refuse a timestamp more than 5 minutes away from your clock.
Node.js
import { createHmac, timingSafeEqual } from "node:crypto";
// secret: the endpoint's signing secret, whsec_…
// headers: the request's headers; body: its raw body, as a string.
export function verifyWebhook(secret, headers, body) {
const id = headers["webhook-id"];
const timestamp = headers["webhook-timestamp"];
const signatures = headers["webhook-signature"];
if (!id || !timestamp || !signatures) return false;
// Refuse a stale delivery, so a replayed one is refused too.
if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
const key = Buffer.from(secret.slice("whsec_".length), "base64");
const expected = createHmac("sha256", key).update(`${id}.${timestamp}.${body}`).digest();
// During a secret rotation the header carries one signature per secret.
return signatures.split(" ").some((part) => {
const [version, value] = part.split(",");
if (version !== "v1" || !value) return false;
const given = Buffer.from(value, "base64");
return given.length === expected.length && timingSafeEqual(given, expected);
});
} When you rotate an endpoint's secret, the old one keeps signing beside the new one for 1 day, so you can update your receiver without missing a delivery.
List webhook endpoints
GET /webhook-endpoints webhookEndpoints.list
Every webhook endpoint in the workspace, oldest first, and every event type an endpoint can subscribe to. A workspace has at most 10 endpoints. Endpoints are registered, and their signing secrets made and rotated, in the admin app only, so no API response carries a secret.
- Scopes
settings.manage- MCP tool
webhook_endpoints_list
Response
200 OK. A JSON object:
Response fields (11)
| Name | Type | Description |
|---|---|---|
endpoints | array of objects | The endpoints, oldest first. |
endpoints[].id | string | The endpoint's id. |
endpoints[].url | string | The https address deliveries are sent to. |
endpoints[].description | string | A note about the endpoint, for people; empty when there is none. |
endpoints[].events | array of strings | The event types sent to it. |
endpoints[].status | string | active: events are sent to it. disabled: it is turned off; no events are recorded for it and nothing is sent. One of active, disabled. |
endpoints[].createdBy | string | The user id of the member who registered it; null when no member did. Can be null. |
endpoints[].createdAt | number | When it was registered, in epoch milliseconds. |
endpoints[].updatedAt | number | When it was last changed, in epoch milliseconds, a new signing secret included. |
endpoints[].previousSecretExpiresAt | number | When the secret replaced by the latest rotation stops signing deliveries, in epoch milliseconds. Until then each delivery is signed with both secrets. Null when no replaced secret still signs. Can be null. |
events | array of strings | Every event type an endpoint can subscribe to. |
Example request
curl https://api.flipbird.io/api/v1/webhook-endpoints \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" Example response
{
"endpoints": [
{
"id": "string",
"url": "https://example.com/privacy",
"description": "Our spring range.",
"events": [
"document.processed"
],
"status": "active",
"createdBy": "string",
"createdAt": 1767225600000,
"updatedAt": 1767225600000,
"previousSecretExpiresAt": 1767225600000
}
],
"events": [
"document.processed"
]
} A webhook endpoint
GET /webhook-endpoints/{endpointId} webhookEndpoints.get
One endpoint, without its signing secret. An unknown endpoint answers 404 not_found.
- Scopes
settings.manage- MCP tool
webhook_endpoints_get
Path parameters
| Name | Type | Description |
|---|---|---|
endpointId required | string | The endpoint's id. An id starting whk_. |
Response
200 OK. A JSON object:
Response fields (9)
| Name | Type | Description |
|---|---|---|
id | string | The endpoint's id. |
url | string | The https address deliveries are sent to. |
description | string | A note about the endpoint, for people; empty when there is none. |
events | array of strings | The event types sent to it. |
status | string | active: events are sent to it. disabled: it is turned off; no events are recorded for it and nothing is sent. One of active, disabled. |
createdBy | string | The user id of the member who registered it; null when no member did. Can be null. |
createdAt | number | When it was registered, in epoch milliseconds. |
updatedAt | number | When it was last changed, in epoch milliseconds, a new signing secret included. |
previousSecretExpiresAt | number | When the secret replaced by the latest rotation stops signing deliveries, in epoch milliseconds. Until then each delivery is signed with both secrets. Null when no replaced secret still signs. Can be null. |
Example request
curl https://api.flipbird.io/api/v1/webhook-endpoints/whk_7m2kq9vx4c8d1r5t6wnb \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" Example response
{
"id": "string",
"url": "https://example.com/privacy",
"description": "Our spring range.",
"events": [
"document.processed"
],
"status": "active",
"createdBy": "string",
"createdAt": 1767225600000,
"updatedAt": 1767225600000,
"previousSecretExpiresAt": 1767225600000
} Change an endpoint's address, events or description, or turn it off
PATCH /webhook-endpoints/{endpointId} webhookEndpoints.update
Changes the fields given and returns the endpoint; a field left out keeps its value. enabled: false turns it off: no events are recorded for it while it is off, and a waiting delivery whose turn comes while it is off becomes dead. Those can be sent again with webhookDeliveries.redeliver once it is on again. The address must be https, on port 443 and on the public internet (400 invalid_url).
When the endpoint is to receive form.submitted after the change, the caller needs the documents.publish.manage permission as well, since that event carries readers' answers to every document's lead form (403 forbidden). An unknown endpoint answers 404 not_found.
- Scopes
settings.manage- Retries
- Safe with an
Idempotency-Key - MCP tool
webhook_endpoints_update
Path parameters
| Name | Type | Description |
|---|---|---|
endpointId required | string | The endpoint's id. An id starting whk_. |
Request body
A JSON object, at most 64 KiB.
| Name | Type | Description |
|---|---|---|
url | string | The https address to send to: port 443, on the public internet, not a Flipbird address, and with no user name or password in it. 1 to 2,048 characters. |
events | array of strings | The event types to send to it, at least one. They replace the ones it had. 1 to 7 items. |
description | string | A note about the endpoint, for people. An empty string clears it. At most 200 characters. |
enabled | boolean | False turns the endpoint off; true turns it back on. |
Response
200 OK. A JSON object:
Response fields (9)
| Name | Type | Description |
|---|---|---|
id | string | The endpoint's id. |
url | string | The https address deliveries are sent to. |
description | string | A note about the endpoint, for people; empty when there is none. |
events | array of strings | The event types sent to it. |
status | string | active: events are sent to it. disabled: it is turned off; no events are recorded for it and nothing is sent. One of active, disabled. |
createdBy | string | The user id of the member who registered it; null when no member did. Can be null. |
createdAt | number | When it was registered, in epoch milliseconds. |
updatedAt | number | When it was last changed, in epoch milliseconds, a new signing secret included. |
previousSecretExpiresAt | number | When the secret replaced by the latest rotation stops signing deliveries, in epoch milliseconds. Until then each delivery is signed with both secrets. Null when no replaced secret still signs. Can be null. |
Example request
curl -X PATCH https://api.flipbird.io/api/v1/webhook-endpoints/whk_7m2kq9vx4c8d1r5t6wnb \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/privacy",
"events": [
"document.processed"
]
}' Example response
{
"id": "string",
"url": "https://example.com/privacy",
"description": "Our spring range.",
"events": [
"document.processed"
],
"status": "active",
"createdBy": "string",
"createdAt": 1767225600000,
"updatedAt": 1767225600000,
"previousSecretExpiresAt": 1767225600000
} Remove a webhook endpoint and its deliveries
DELETE /webhook-endpoints/{endpointId} webhookEndpoints.delete
Removes the endpoint and every delivery to it, sent or not; nothing more is sent to it. An unknown endpoint answers 404 not_found. Returns an empty object.
- Scopes
settings.manage- Retries
- Safe with an
Idempotency-Key - MCP tool
webhook_endpoints_delete
Path parameters
| Name | Type | Description |
|---|---|---|
endpointId required | string | The endpoint's id. An id starting whk_. |
Response
200 OK. An empty JSON object, {}.
Example request
curl -X DELETE https://api.flipbird.io/api/v1/webhook-endpoints/whk_7m2kq9vx4c8d1r5t6wnb \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" An endpoint's deliveries, newest first
GET /webhook-endpoints/{endpointId}/deliveries webhookDeliveries.list
One delivery per event sent to the endpoint, newest first. Filter by status; for the next page, pass nextCursor as cursor. An attempt succeeds when the endpoint answers with a 2xx status within 10 seconds; redirects are not followed. A failed attempt is tried again after 30 seconds, then after three times as long each time, 8 attempts in all (about nine hours); then the delivery is dead.
Deliveries and their events are kept for 30 days. An unknown endpoint answers 404 not_found.
- Scopes
settings.manage- MCP tool
webhook_deliveries_list
Path parameters
| Name | Type | Description |
|---|---|---|
endpointId required | string | The endpoint's id. An id starting whk_. |
Query parameters
| Name | Type | Description |
|---|---|---|
status | string | Only deliveries in this status. One of pending, delivering, succeeded, dead. |
cursor | string | nextCursor from the previous page, to read the next one. Matches ^\d{1,16}(\.[A-Za-z0-9_-]{1,64}){1,2}$. |
before | integer | The older way to page: only deliveries made before this time, in epoch milliseconds. It skips deliveries that share the last one's createdAt; use cursor. Ignored when cursor is given. More than 0. |
limit | integer | Most deliveries to return. Default 50. 1 to 200. |
Response
200 OK. A JSON object:
Response fields (13)
| Name | Type | Description |
|---|---|---|
deliveries | array of objects | The deliveries, newest first. |
deliveries[].eventId | string | The event's id, evt_ and more. It is the same for every endpoint the event goes to, and is sent as the delivery's webhook-id header. |
deliveries[].endpointId | string | The endpoint the delivery goes to. |
deliveries[].eventType | string | The event's type, such as document.processed. |
deliveries[].status | string | pending: waiting for its next attempt, due at nextAttemptAt. delivering: an attempt is under way. succeeded: the endpoint answered an attempt with a 2xx status. dead: it ran out of attempts, or its endpoint was turned off when its turn came; it is not tried again unless sent again with webhookDeliveries.redeliver. One of pending, delivering, succeeded, dead. |
deliveries[].attempts | number | Attempts made so far, at most 8. Sending it again with webhookDeliveries.redeliver starts the count again. |
deliveries[].nextAttemptAt | number | When the next attempt is due, in epoch milliseconds, while pending; null in any other status. Can be null. |
deliveries[].lastAttemptAt | number | When the latest attempt started, in epoch milliseconds; null before the first. Can be null. |
deliveries[].lastStatusCode | number | The HTTP status the endpoint answered the latest attempt with; null before the first attempt, or when it gave none (it did not answer in time, could not be reached, or the attempt was refused before sending). Can be null. |
deliveries[].lastError | string | Why the latest attempt failed, in a sentence for people. Null before the first attempt, when the latest attempt succeeded, and after webhookDeliveries.redeliver until an attempt fails. Can be null. |
deliveries[].deliveredAt | number | When the endpoint last accepted it, in epoch milliseconds; null if it never has. Can be null. |
deliveries[].createdAt | number | When the event happened, in epoch milliseconds. |
nextCursor | string | Pass as cursor to read the next page. Null when this page is not full; a full page may be followed by an empty one. Can be null. |
Example request
curl https://api.flipbird.io/api/v1/webhook-endpoints/whk_7m2kq9vx4c8d1r5t6wnb/deliveries \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" Example response
{
"deliveries": [
{
"eventId": "…",
"endpointId": "…",
"eventType": "string",
"status": "pending",
"attempts": 1,
"nextAttemptAt": 1767225600000,
"lastAttemptAt": 1767225600000,
"lastStatusCode": 1,
"lastError": "string",
"deliveredAt": 1767225600000,
"createdAt": 1767225600000
}
],
"nextCursor": "string"
} Deliveries that ran out of attempts, across every endpoint
GET /webhook-deliveries/dead webhookDeliveries.dead
Every delivery in the dead status, across every endpoint, newest first: those that ran out of their 8 attempts, and those whose endpoint was turned off when their turn came. Each can be sent again with webhookDeliveries.redeliver. For the next page, pass nextCursor as cursor. Deliveries and their events are kept for 30 days, then removed, dead or not.
- Scopes
settings.manage- MCP tool
webhook_dead_letters
Query parameters
| Name | Type | Description |
|---|---|---|
cursor | string | nextCursor from the previous page, to read the next one. Matches ^\d{1,16}(\.[A-Za-z0-9_-]{1,64}){1,2}$. |
before | integer | The older way to page: only deliveries made before this time, in epoch milliseconds. It skips deliveries that share the last one's createdAt; use cursor. Ignored when cursor is given. More than 0. |
limit | integer | Most deliveries to return. Default 50. 1 to 200. |
Response
200 OK. A JSON object:
Response fields (13)
| Name | Type | Description |
|---|---|---|
deliveries | array of objects | The dead deliveries, newest first. |
deliveries[].eventId | string | The event's id, evt_ and more. It is the same for every endpoint the event goes to, and is sent as the delivery's webhook-id header. |
deliveries[].endpointId | string | The endpoint the delivery goes to. |
deliveries[].eventType | string | The event's type, such as document.processed. |
deliveries[].status | string | pending: waiting for its next attempt, due at nextAttemptAt. delivering: an attempt is under way. succeeded: the endpoint answered an attempt with a 2xx status. dead: it ran out of attempts, or its endpoint was turned off when its turn came; it is not tried again unless sent again with webhookDeliveries.redeliver. One of pending, delivering, succeeded, dead. |
deliveries[].attempts | number | Attempts made so far, at most 8. Sending it again with webhookDeliveries.redeliver starts the count again. |
deliveries[].nextAttemptAt | number | When the next attempt is due, in epoch milliseconds, while pending; null in any other status. Can be null. |
deliveries[].lastAttemptAt | number | When the latest attempt started, in epoch milliseconds; null before the first. Can be null. |
deliveries[].lastStatusCode | number | The HTTP status the endpoint answered the latest attempt with; null before the first attempt, or when it gave none (it did not answer in time, could not be reached, or the attempt was refused before sending). Can be null. |
deliveries[].lastError | string | Why the latest attempt failed, in a sentence for people. Null before the first attempt, when the latest attempt succeeded, and after webhookDeliveries.redeliver until an attempt fails. Can be null. |
deliveries[].deliveredAt | number | When the endpoint last accepted it, in epoch milliseconds; null if it never has. Can be null. |
deliveries[].createdAt | number | When the event happened, in epoch milliseconds. |
nextCursor | string | Pass as cursor to read the next page. Null when this page is not full; a full page may be followed by an empty one. Can be null. |
Example request
curl https://api.flipbird.io/api/v1/webhook-deliveries/dead \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" Example response
{
"deliveries": [
{
"eventId": "…",
"endpointId": "…",
"eventType": "string",
"status": "pending",
"attempts": 1,
"nextAttemptAt": 1767225600000,
"lastAttemptAt": 1767225600000,
"lastStatusCode": 1,
"lastError": "string",
"deliveredAt": 1767225600000,
"createdAt": 1767225600000
}
],
"nextCursor": "string"
} Send a finished delivery again, from its first attempt
POST /webhook-endpoints/{endpointId}/deliveries/{eventId}/redeliver webhookDeliveries.redeliver
Starts a succeeded or dead delivery over: its attempts go back to 0 and it is queued to be sent at once, with the same event id and body, so a receiver can tell a repeat by its webhook-id. A failure is retried on the usual schedule. Returns the delivery as it stands, normally pending, with status 202.
A delivery that is still pending or delivering, or that does not exist, answers 409 conflict; an endpoint that is turned off, 409 endpoint_disabled; an unknown endpoint, 404 not_found. An event older than 30 days is gone and cannot be sent again.
- Scopes
settings.manage- Retries
- Safe with an
Idempotency-Key - MCP tool
webhook_deliveries_redeliver
Path parameters
| Name | Type | Description |
|---|---|---|
endpointId required | string | The endpoint's id. An id starting whk_. |
eventId required | string | The event's id, as the delivery's eventId gives it. An id starting evt_. |
Response
202 Accepted. A JSON object:
Response fields (11)
| Name | Type | Description |
|---|---|---|
eventId | string | The event's id, evt_ and more. It is the same for every endpoint the event goes to, and is sent as the delivery's webhook-id header. |
endpointId | string | The endpoint the delivery goes to. |
eventType | string | The event's type, such as document.processed. |
status | string | pending: waiting for its next attempt, due at nextAttemptAt. delivering: an attempt is under way. succeeded: the endpoint answered an attempt with a 2xx status. dead: it ran out of attempts, or its endpoint was turned off when its turn came; it is not tried again unless sent again with webhookDeliveries.redeliver. One of pending, delivering, succeeded, dead. |
attempts | number | Attempts made so far, at most 8. Sending it again with webhookDeliveries.redeliver starts the count again. |
nextAttemptAt | number | When the next attempt is due, in epoch milliseconds, while pending; null in any other status. Can be null. |
lastAttemptAt | number | When the latest attempt started, in epoch milliseconds; null before the first. Can be null. |
lastStatusCode | number | The HTTP status the endpoint answered the latest attempt with; null before the first attempt, or when it gave none (it did not answer in time, could not be reached, or the attempt was refused before sending). Can be null. |
lastError | string | Why the latest attempt failed, in a sentence for people. Null before the first attempt, when the latest attempt succeeded, and after webhookDeliveries.redeliver until an attempt fails. Can be null. |
deliveredAt | number | When the endpoint last accepted it, in epoch milliseconds; null if it never has. Can be null. |
createdAt | number | When the event happened, in epoch milliseconds. |
Example request
curl -X POST https://api.flipbird.io/api/v1/webhook-endpoints/whk_7m2kq9vx4c8d1r5t6wnb/deliveries/evt_7m2kq9vx4c8d1r5t6wnb/redeliver \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" Example response
{
"eventId": "…",
"endpointId": "…",
"eventType": "string",
"status": "pending",
"attempts": 1,
"nextAttemptAt": 1767225600000,
"lastAttemptAt": 1767225600000,
"lastStatusCode": 1,
"lastError": "string",
"deliveredAt": 1767225600000,
"createdAt": 1767225600000
} Errors
Besides the errors any endpoint can answer, these endpoints answer:
| Status | Code | When |
|---|---|---|
| 400 | invalid_url | The address is not https on port 443 on the public internet. |
| 400 | bad_cursor | The cursor was not given by this list. |
| 409 | endpoint_disabled | Redelivering to an endpoint that is turned off. |
| 409 | conflict | Redelivering a delivery that has not finished, or does not exist. |