API reference

Webhook endpoints

Register the URLs that receive events, rotate their signing secrets, send test events and work with the delivery log. Organization admins can do the same in the Flux app under Settings → Developers.

Endpoint	What it does
GET `/api/v1/webhook-endpoints`	List endpoints
POST `/api/v1/webhook-endpoints`	Register an endpoint
GET `/api/v1/webhook-endpoints/{id}`	Get an endpoint
PATCH `/api/v1/webhook-endpoints/{id}`	Update an endpoint
DELETE `/api/v1/webhook-endpoints/{id}`	Delete an endpoint
POST `/api/v1/webhook-endpoints/{id}/rotate-secret`	Rotate the signing secret
POST `/api/v1/webhook-endpoints/{id}/test`	Send a test event
GET `/api/v1/webhook-endpoints/{id}/deliveries`	List deliveries
POST `/api/v1/webhook-deliveries/{id}/redeliver`	Redeliver

All these endpoints need the webhooks:manage scope. To receive and verify events, see Receiving webhooks.

The endpoint object#

A URL that receives events.

Field	Description
idinteger	Endpoint id.
urlstring	Where events are sent.
descriptionstring · nullable	Your label.
eventsarray of strings	Event types it receives, or `["*"]` for all.
activeboolean	Whether it receives events.
disabledReasonstring · nullable	Why Flux switched it off, if it did.
consecutiveFailuresinteger	Failed delivery attempts in a row. At 50, Flux switches the endpoint off.
createdAttimestamp	When it was created. UTC, no offset.
secretstring · nullable	The signing secret, `whsec_…`. Only on create and rotate, shown once; `null` otherwise.

Webhook endpoint

{
  "id": 3,
  "url": "https://hooks.example.com/flux",
  "description": "Billing sync",
  "events": ["invoice.paid", "receipt.issued"],
  "active": true,
  "disabledReason": null,
  "consecutiveFailures": 0,
  "createdAt": "2026-11-01T10:00:00",
  "secret": "whsec_Xq3vT8mKp2Lr7Ns1Wd5Yb9Hc4Fj6Ga0Z"
}

The delivery object#

One event sent to one endpoint, with its attempt history.

Delivery status: pending (waiting to be sent or retried), delivered (your endpoint returned 2xx), dead (all 10 attempts failed) or cancelled (the endpoint was deleted).

Field	Description
idinteger (64-bit)	Delivery id. Use it to redeliver.
eventIdstring	The event, `evt_…`. Same as the `Flux-Event-Id` header.
eventTypestring	The event type.
statusstring	Delivery state. One of `pending`, `delivered`, `dead`, `cancelled`.
attemptsinteger	Attempts so far. At most 10 before `dead`, plus any redeliveries.
lastStatusCodeinteger · nullable	HTTP status of the last attempt.
lastErrorstring · nullable	What went wrong on the last attempt, up to 500 characters.
nextAttemptAttimestamp · nullable	When the next retry is due. UTC, no offset.
lastAttemptAttimestamp · nullable	UTC, no offset.
deliveredAttimestamp · nullable	When your endpoint returned 2xx. UTC, no offset.
createdAttimestamp	When the delivery was queued. UTC, no offset.

Delivery

{
  "id": 99001,
  "eventId": "evt_01JC8Z5T6Q1W3M4N5P6R7S8T9V",
  "eventType": "invoice.paid",
  "status": "delivered",
  "attempts": 1,
  "lastStatusCode": 200,
  "lastError": null,
  "nextAttemptAt": null,
  "lastAttemptAt": "2026-11-03T14:02:05",
  "deliveredAt": "2026-11-03T14:02:05",
  "createdAt": "2026-11-03T14:02:04"
}

List endpoints#

GET/api/v1/webhook-endpointswebhooks:manage

All the organization's webhook endpoints, as an array, oldest first.

Request

curl "$FLUX_BASE_URL/api/v1/webhook-endpoints" \
  -H "Authorization: ApiKey $FLUX_API_KEY"

// Node.js 18+ (built-in fetch). Save as an .mjs file.
const response = await fetch(`${process.env.FLUX_BASE_URL}/api/v1/webhook-endpoints`, {
  headers: {
    Authorization: `ApiKey ${process.env.FLUX_API_KEY}`,
  },
});
console.log(response.status, await response.json());

import os

import requests

response = requests.get(
    f"{os.environ['FLUX_BASE_URL']}/api/v1/webhook-endpoints",
    headers={"Authorization": f"ApiKey {os.environ['FLUX_API_KEY']}"},
    timeout=30,
)
print(response.status_code, response.json())

<?php
$ch = curl_init(getenv('FLUX_BASE_URL') . '/api/v1/webhook-endpoints');
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => [
        'Authorization: ApiKey ' . getenv('FLUX_API_KEY'),
    ],
    CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), ' ', $response, PHP_EOL;

using System.Net.Http.Headers;

var baseUrl = Environment.GetEnvironmentVariable("FLUX_BASE_URL");
using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("ApiKey", Environment.GetEnvironmentVariable("FLUX_API_KEY"));

using var request = new HttpRequestMessage(HttpMethod.Get, $"{baseUrl}/api/v1/webhook-endpoints");

using var response = await http.SendAsync(request);
Console.WriteLine($"{(int)response.StatusCode} {await response.Content.ReadAsStringAsync()}");

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("GET", os.Getenv("FLUX_BASE_URL")+"/api/v1/webhook-endpoints", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "ApiKey "+os.Getenv("FLUX_API_KEY"))

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	out, _ := io.ReadAll(resp.Body)
	fmt.Println(resp.StatusCode, string(out))
}

Responses

200 OK

[
  {
    "id": 3,
    "url": "https://hooks.example.com/flux",
    "description": "Billing sync",
    "events": ["invoice.paid", "receipt.issued"],
    "active": true,
    "disabledReason": null,
    "consecutiveFailures": 0,
    "createdAt": "2026-11-01T10:00:00",
    "secret": null
  }
]

3 possible errors

Status	Code	When
`401`	`unauthorized`	No API key, an unknown key or a revoked key.
`403`	`insufficient_scope`	The key lacks the scope. `details` names it: `{ "required": "invoices:write" }`.
`429`	`rate_limited`	Too many requests for this key. Wait for the `Retry-After` seconds.

Register an endpoint#

POST/api/v1/webhook-endpointswebhooks:manageIdempotency-Key

Registers a URL to receive events. The response includes the signing secret. It's shown once: store it in your secret manager straight away.

Request body

Field	Description
urlstring	required An absolute `https` URL of at most 500 characters, publicly reachable. Required on create.
descriptionstring	optional At most 200 characters.
eventsarray of strings	required At least one known event type, or `["*"]` for all. Required on create.
activeboolean	optional Default `true`. Setting `true` re-enables a disabled endpoint and resets its failure count.

The URL must be an absolute https URL of at most 500 characters, with no credentials in it. It can't be or resolve to a loopback, private, link-local or carrier-grade NAT address; Flux checks this again on every delivery. Flux doesn't follow redirects. events must contain at least one known event type, or "*" for all.

Request

curl -X POST "$FLUX_BASE_URL/api/v1/webhook-endpoints" \
  -H "Authorization: ApiKey $FLUX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: endpoint-billing-sync" \
  -d '{
  "url": "https://hooks.example.com/flux",
  "description": "Billing sync",
  "events": ["invoice.paid", "receipt.issued"]
}'

// Node.js 18+ (built-in fetch). Save as an .mjs file.
const response = await fetch(`${process.env.FLUX_BASE_URL}/api/v1/webhook-endpoints`, {
  method: "POST",
  headers: {
    Authorization: `ApiKey ${process.env.FLUX_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "endpoint-billing-sync",
  },
  body: JSON.stringify({
    url: "https://hooks.example.com/flux",
    description: "Billing sync",
    events: ["invoice.paid", "receipt.issued"],
  }),
});
console.log(response.status, await response.json());

import os

import requests

response = requests.post(
    f"{os.environ['FLUX_BASE_URL']}/api/v1/webhook-endpoints",
    headers={
        "Authorization": f"ApiKey {os.environ['FLUX_API_KEY']}",
        "Idempotency-Key": "endpoint-billing-sync",
    },
    json={
        "url": "https://hooks.example.com/flux",
        "description": "Billing sync",
        "events": ["invoice.paid", "receipt.issued"],
    },
    timeout=30,
)
print(response.status_code, response.json())

<?php
$body = <<<'JSON'
{
  "url": "https://hooks.example.com/flux",
  "description": "Billing sync",
  "events": ["invoice.paid", "receipt.issued"]
}
JSON;

$ch = curl_init(getenv('FLUX_BASE_URL') . '/api/v1/webhook-endpoints');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'Authorization: ApiKey ' . getenv('FLUX_API_KEY'),
        'Content-Type: application/json',
        'Idempotency-Key: endpoint-billing-sync',
    ],
    CURLOPT_POSTFIELDS => $body,
    CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), ' ', $response, PHP_EOL;

using System.Net.Http.Headers;
using System.Text;

var baseUrl = Environment.GetEnvironmentVariable("FLUX_BASE_URL");
using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("ApiKey", Environment.GetEnvironmentVariable("FLUX_API_KEY"));

using var request = new HttpRequestMessage(HttpMethod.Post, $"{baseUrl}/api/v1/webhook-endpoints");
request.Headers.Add("Idempotency-Key", "endpoint-billing-sync");
request.Content = new StringContent("""
    {
      "url": "https://hooks.example.com/flux",
      "description": "Billing sync",
      "events": ["invoice.paid", "receipt.issued"]
    }
    """, Encoding.UTF8, "application/json");

using var response = await http.SendAsync(request);
Console.WriteLine($"{(int)response.StatusCode} {await response.Content.ReadAsStringAsync()}");

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
	"strings"
)

func main() {
	body := strings.NewReader(`{
	  "url": "https://hooks.example.com/flux",
	  "description": "Billing sync",
	  "events": ["invoice.paid", "receipt.issued"]
	}`)
	req, err := http.NewRequest("POST", os.Getenv("FLUX_BASE_URL")+"/api/v1/webhook-endpoints", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "ApiKey "+os.Getenv("FLUX_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Idempotency-Key", "endpoint-billing-sync")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	out, _ := io.ReadAll(resp.Body)
	fmt.Println(resp.StatusCode, string(out))
}

Responses

201 Created

{
  "id": 3,
  "url": "https://hooks.example.com/flux",
  "description": "Billing sync",
  "events": ["invoice.paid", "receipt.issued"],
  "active": true,
  "disabledReason": null,
  "consecutiveFailures": 0,
  "createdAt": "2026-11-01T10:00:00",
  "secret": "whsec_Xq3vT8mKp2Lr7Ns1Wd5Yb9Hc4Fj6Ga0Z"
}

7 possible errors

Status	Code	When
`400`	`invalid_request`	Validation failed. The `message` says what, such as Add at least one invoice item.
`400`	`invalid_idempotency_key`	`Idempotency-Key` is longer than 255 characters.
`409`	`idempotency_in_progress`	A request with the same `Idempotency-Key` is still running.
`422`	`idempotency_key_reused`	The same `Idempotency-Key` was sent with a different request.
`401`	`unauthorized`	No API key, an unknown key or a revoked key.
`403`	`insufficient_scope`	The key lacks the scope. `details` names it: `{ "required": "invoices:write" }`.
`429`	`rate_limited`	Too many requests for this key. Wait for the `Retry-After` seconds.

Get an endpoint#

GET/api/v1/webhook-endpoints/{id}webhooks:manage

Returns one endpoint. secret is null.

Path parameters

Field	Description
idinteger	required The webhook endpoint's id.

Request

curl "$FLUX_BASE_URL/api/v1/webhook-endpoints/3" \
  -H "Authorization: ApiKey $FLUX_API_KEY"

// Node.js 18+ (built-in fetch). Save as an .mjs file.
const response = await fetch(`${process.env.FLUX_BASE_URL}/api/v1/webhook-endpoints/3`, {
  headers: {
    Authorization: `ApiKey ${process.env.FLUX_API_KEY}`,
  },
});
console.log(response.status, await response.json());

import os

import requests

response = requests.get(
    f"{os.environ['FLUX_BASE_URL']}/api/v1/webhook-endpoints/3",
    headers={"Authorization": f"ApiKey {os.environ['FLUX_API_KEY']}"},
    timeout=30,
)
print(response.status_code, response.json())

<?php
$ch = curl_init(getenv('FLUX_BASE_URL') . '/api/v1/webhook-endpoints/3');
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => [
        'Authorization: ApiKey ' . getenv('FLUX_API_KEY'),
    ],
    CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), ' ', $response, PHP_EOL;

using System.Net.Http.Headers;

var baseUrl = Environment.GetEnvironmentVariable("FLUX_BASE_URL");
using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("ApiKey", Environment.GetEnvironmentVariable("FLUX_API_KEY"));

using var request = new HttpRequestMessage(HttpMethod.Get, $"{baseUrl}/api/v1/webhook-endpoints/3");

using var response = await http.SendAsync(request);
Console.WriteLine($"{(int)response.StatusCode} {await response.Content.ReadAsStringAsync()}");

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("GET", os.Getenv("FLUX_BASE_URL")+"/api/v1/webhook-endpoints/3", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "ApiKey "+os.Getenv("FLUX_API_KEY"))

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	out, _ := io.ReadAll(resp.Body)
	fmt.Println(resp.StatusCode, string(out))
}

Responses

200 OK

{
  "id": 3,
  "url": "https://hooks.example.com/flux",
  "description": "Billing sync",
  "events": ["invoice.paid", "receipt.issued"],
  "active": true,
  "disabledReason": null,
  "consecutiveFailures": 0,
  "createdAt": "2026-11-01T10:00:00",
  "secret": null
}

4 possible errors

Status	Code	When
`404`	`not_found`	Unknown id, or an id that belongs to another organization.
`401`	`unauthorized`	No API key, an unknown key or a revoked key.
`403`	`insufficient_scope`	The key lacks the scope. `details` names it: `{ "required": "invoices:write" }`.
`429`	`rate_limited`	Too many requests for this key. Wait for the `Retry-After` seconds.

Update an endpoint#

PATCH/api/v1/webhook-endpoints/{id}webhooks:manage

Changes the URL, events, description or active state. Setting active: true re-enables an endpoint Flux switched off, and resets its failure count.

Path parameters

Field	Description
idinteger	required The webhook endpoint's id.

Request body

Field	Description
urlstring	optional An absolute `https` URL of at most 500 characters, publicly reachable. Required on create.
descriptionstring	optional At most 200 characters.
eventsarray of strings	optional At least one known event type, or `["*"]` for all. Required on create.
activeboolean	optional Default `true`. Setting `true` re-enables a disabled endpoint and resets its failure count.

Request

curl -X PATCH "$FLUX_BASE_URL/api/v1/webhook-endpoints/3" \
  -H "Authorization: ApiKey $FLUX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "active": true
}'

// Node.js 18+ (built-in fetch). Save as an .mjs file.
const response = await fetch(`${process.env.FLUX_BASE_URL}/api/v1/webhook-endpoints/3`, {
  method: "PATCH",
  headers: {
    Authorization: `ApiKey ${process.env.FLUX_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    active: true,
  }),
});
console.log(response.status, await response.json());

import os

import requests

response = requests.patch(
    f"{os.environ['FLUX_BASE_URL']}/api/v1/webhook-endpoints/3",
    headers={"Authorization": f"ApiKey {os.environ['FLUX_API_KEY']}"},
    json={
        "active": True,
    },
    timeout=30,
)
print(response.status_code, response.json())

<?php
$body = <<<'JSON'
{
  "active": true
}
JSON;

$ch = curl_init(getenv('FLUX_BASE_URL') . '/api/v1/webhook-endpoints/3');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'PATCH',
    CURLOPT_HTTPHEADER => [
        'Authorization: ApiKey ' . getenv('FLUX_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => $body,
    CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), ' ', $response, PHP_EOL;

using System.Net.Http.Headers;
using System.Text;

var baseUrl = Environment.GetEnvironmentVariable("FLUX_BASE_URL");
using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("ApiKey", Environment.GetEnvironmentVariable("FLUX_API_KEY"));

using var request = new HttpRequestMessage(HttpMethod.Patch, $"{baseUrl}/api/v1/webhook-endpoints/3");
request.Content = new StringContent("""
    {
      "active": true
    }
    """, Encoding.UTF8, "application/json");

using var response = await http.SendAsync(request);
Console.WriteLine($"{(int)response.StatusCode} {await response.Content.ReadAsStringAsync()}");

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
	"strings"
)

func main() {
	body := strings.NewReader(`{
	  "active": true
	}`)
	req, err := http.NewRequest("PATCH", os.Getenv("FLUX_BASE_URL")+"/api/v1/webhook-endpoints/3", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "ApiKey "+os.Getenv("FLUX_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	out, _ := io.ReadAll(resp.Body)
	fmt.Println(resp.StatusCode, string(out))
}

Responses

200 OK

{
  "id": 3,
  "url": "https://hooks.example.com/flux",
  "description": "Billing sync",
  "events": ["invoice.paid", "receipt.issued"],
  "active": true,
  "disabledReason": null,
  "consecutiveFailures": 0,
  "createdAt": "2026-11-01T10:00:00",
  "secret": null
}

5 possible errors

Status	Code	When
`400`	`invalid_request`	Validation failed. The `message` says what, such as Add at least one invoice item.
`404`	`not_found`	Unknown id, or an id that belongs to another organization.
`401`	`unauthorized`	No API key, an unknown key or a revoked key.
`403`	`insufficient_scope`	The key lacks the scope. `details` names it: `{ "required": "invoices:write" }`.
`429`	`rate_limited`	Too many requests for this key. Wait for the `Retry-After` seconds.

Delete an endpoint#

DELETE/api/v1/webhook-endpoints/{id}webhooks:manage

Deletes the endpoint and cancels its pending deliveries.

Path parameters

Field	Description
idinteger	required The webhook endpoint's id.

Request

curl -X DELETE "$FLUX_BASE_URL/api/v1/webhook-endpoints/3" \
  -H "Authorization: ApiKey $FLUX_API_KEY"

// Node.js 18+ (built-in fetch). Save as an .mjs file.
const response = await fetch(`${process.env.FLUX_BASE_URL}/api/v1/webhook-endpoints/3`, {
  method: "DELETE",
  headers: {
    Authorization: `ApiKey ${process.env.FLUX_API_KEY}`,
  },
});
console.log(response.status, await response.text());

import os

import requests

response = requests.delete(
    f"{os.environ['FLUX_BASE_URL']}/api/v1/webhook-endpoints/3",
    headers={"Authorization": f"ApiKey {os.environ['FLUX_API_KEY']}"},
    timeout=30,
)
print(response.status_code, response.text)

<?php
$ch = curl_init(getenv('FLUX_BASE_URL') . '/api/v1/webhook-endpoints/3');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'DELETE',
    CURLOPT_HTTPHEADER => [
        'Authorization: ApiKey ' . getenv('FLUX_API_KEY'),
    ],
    CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), ' ', $response, PHP_EOL;

using System.Net.Http.Headers;

var baseUrl = Environment.GetEnvironmentVariable("FLUX_BASE_URL");
using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("ApiKey", Environment.GetEnvironmentVariable("FLUX_API_KEY"));

using var request = new HttpRequestMessage(HttpMethod.Delete, $"{baseUrl}/api/v1/webhook-endpoints/3");

using var response = await http.SendAsync(request);
Console.WriteLine($"{(int)response.StatusCode} {await response.Content.ReadAsStringAsync()}");

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("DELETE", os.Getenv("FLUX_BASE_URL")+"/api/v1/webhook-endpoints/3", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "ApiKey "+os.Getenv("FLUX_API_KEY"))

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	out, _ := io.ReadAll(resp.Body)
	fmt.Println(resp.StatusCode, string(out))
}

Responses

204 No Content

No body.

4 possible errors

Status	Code	When
`404`	`not_found`	Unknown id, or an id that belongs to another organization.
`401`	`unauthorized`	No API key, an unknown key or a revoked key.
`403`	`insufficient_scope`	The key lacks the scope. `details` names it: `{ "required": "invoices:write" }`.
`429`	`rate_limited`	Too many requests for this key. Wait for the `Retry-After` seconds.

Rotate the signing secret#

POST/api/v1/webhook-endpoints/{id}/rotate-secretwebhooks:manage

Creates a new signing secret and returns it once. The old secret stops working immediately, so deploy the new one promptly. See Rotate keys and secrets.

Path parameters

Field	Description
idinteger	required The webhook endpoint's id.

Request

curl -X POST "$FLUX_BASE_URL/api/v1/webhook-endpoints/3/rotate-secret" \
  -H "Authorization: ApiKey $FLUX_API_KEY"

// Node.js 18+ (built-in fetch). Save as an .mjs file.
const response = await fetch(`${process.env.FLUX_BASE_URL}/api/v1/webhook-endpoints/3/rotate-secret`, {
  method: "POST",
  headers: {
    Authorization: `ApiKey ${process.env.FLUX_API_KEY}`,
  },
});
console.log(response.status, await response.json());

import os

import requests

response = requests.post(
    f"{os.environ['FLUX_BASE_URL']}/api/v1/webhook-endpoints/3/rotate-secret",
    headers={"Authorization": f"ApiKey {os.environ['FLUX_API_KEY']}"},
    timeout=30,
)
print(response.status_code, response.json())

<?php
$ch = curl_init(getenv('FLUX_BASE_URL') . '/api/v1/webhook-endpoints/3/rotate-secret');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'Authorization: ApiKey ' . getenv('FLUX_API_KEY'),
    ],
    CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), ' ', $response, PHP_EOL;

using System.Net.Http.Headers;

var baseUrl = Environment.GetEnvironmentVariable("FLUX_BASE_URL");
using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("ApiKey", Environment.GetEnvironmentVariable("FLUX_API_KEY"));

using var request = new HttpRequestMessage(HttpMethod.Post, $"{baseUrl}/api/v1/webhook-endpoints/3/rotate-secret");

using var response = await http.SendAsync(request);
Console.WriteLine($"{(int)response.StatusCode} {await response.Content.ReadAsStringAsync()}");

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("POST", os.Getenv("FLUX_BASE_URL")+"/api/v1/webhook-endpoints/3/rotate-secret", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "ApiKey "+os.Getenv("FLUX_API_KEY"))

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	out, _ := io.ReadAll(resp.Body)
	fmt.Println(resp.StatusCode, string(out))
}

Responses

200 OK

{
  "id": 3,
  "url": "https://hooks.example.com/flux",
  "description": "Billing sync",
  "events": ["invoice.paid", "receipt.issued"],
  "active": true,
  "disabledReason": null,
  "consecutiveFailures": 0,
  "createdAt": "2026-11-01T10:00:00",
  "secret": "whsec_P7nR2kV9cX4mT1bQ8wL5yJ3hD6gF0sZa"
}

4 possible errors

Status	Code	When
`404`	`not_found`	Unknown id, or an id that belongs to another organization.
`401`	`unauthorized`	No API key, an unknown key or a revoked key.
`403`	`insufficient_scope`	The key lacks the scope. `details` names it: `{ "required": "invoices:write" }`.
`429`	`rate_limited`	Too many requests for this key. Wait for the `Retry-After` seconds.

Send a test event#

POST/api/v1/webhook-endpoints/{id}/testwebhooks:manage

Queues a webhook.test event to this endpoint only. It's signed and retried like any other event.

Path parameters

Field	Description
idinteger	required The webhook endpoint's id.

Request

curl -X POST "$FLUX_BASE_URL/api/v1/webhook-endpoints/3/test" \
  -H "Authorization: ApiKey $FLUX_API_KEY"

// Node.js 18+ (built-in fetch). Save as an .mjs file.
const response = await fetch(`${process.env.FLUX_BASE_URL}/api/v1/webhook-endpoints/3/test`, {
  method: "POST",
  headers: {
    Authorization: `ApiKey ${process.env.FLUX_API_KEY}`,
  },
});
console.log(response.status, await response.text());

import os

import requests

response = requests.post(
    f"{os.environ['FLUX_BASE_URL']}/api/v1/webhook-endpoints/3/test",
    headers={"Authorization": f"ApiKey {os.environ['FLUX_API_KEY']}"},
    timeout=30,
)
print(response.status_code, response.text)

<?php
$ch = curl_init(getenv('FLUX_BASE_URL') . '/api/v1/webhook-endpoints/3/test');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'Authorization: ApiKey ' . getenv('FLUX_API_KEY'),
    ],
    CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), ' ', $response, PHP_EOL;

using System.Net.Http.Headers;

var baseUrl = Environment.GetEnvironmentVariable("FLUX_BASE_URL");
using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("ApiKey", Environment.GetEnvironmentVariable("FLUX_API_KEY"));

using var request = new HttpRequestMessage(HttpMethod.Post, $"{baseUrl}/api/v1/webhook-endpoints/3/test");

using var response = await http.SendAsync(request);
Console.WriteLine($"{(int)response.StatusCode} {await response.Content.ReadAsStringAsync()}");

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("POST", os.Getenv("FLUX_BASE_URL")+"/api/v1/webhook-endpoints/3/test", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "ApiKey "+os.Getenv("FLUX_API_KEY"))

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	out, _ := io.ReadAll(resp.Body)
	fmt.Println(resp.StatusCode, string(out))
}

Responses

202 Accepted

No body. The delivery appears in the delivery log.

4 possible errors

Status	Code	When
`404`	`not_found`	Unknown id, or an id that belongs to another organization.
`401`	`unauthorized`	No API key, an unknown key or a revoked key.
`403`	`insufficient_scope`	The key lacks the scope. `details` names it: `{ "required": "invoices:write" }`.
`429`	`rate_limited`	Too many requests for this key. Wait for the `Retry-After` seconds.

List deliveries#

GET/api/v1/webhook-endpoints/{id}/deliverieswebhooks:manage

The endpoint's delivery log, newest first.

Path parameters

Field	Description
idinteger	required The webhook endpoint's id.

Query parameters

Field	Description
limitinteger	Items per page, 1 to 100. Default 25.
cursorstring	The `nextCursor` from the previous page. Leave it out for the first page.

Request

curl "$FLUX_BASE_URL/api/v1/webhook-endpoints/3/deliveries" \
  -H "Authorization: ApiKey $FLUX_API_KEY"

// Node.js 18+ (built-in fetch). Save as an .mjs file.
const response = await fetch(`${process.env.FLUX_BASE_URL}/api/v1/webhook-endpoints/3/deliveries`, {
  headers: {
    Authorization: `ApiKey ${process.env.FLUX_API_KEY}`,
  },
});
console.log(response.status, await response.json());

import os

import requests

response = requests.get(
    f"{os.environ['FLUX_BASE_URL']}/api/v1/webhook-endpoints/3/deliveries",
    headers={"Authorization": f"ApiKey {os.environ['FLUX_API_KEY']}"},
    timeout=30,
)
print(response.status_code, response.json())

<?php
$ch = curl_init(getenv('FLUX_BASE_URL') . '/api/v1/webhook-endpoints/3/deliveries');
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => [
        'Authorization: ApiKey ' . getenv('FLUX_API_KEY'),
    ],
    CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), ' ', $response, PHP_EOL;

using System.Net.Http.Headers;

var baseUrl = Environment.GetEnvironmentVariable("FLUX_BASE_URL");
using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("ApiKey", Environment.GetEnvironmentVariable("FLUX_API_KEY"));

using var request = new HttpRequestMessage(HttpMethod.Get, $"{baseUrl}/api/v1/webhook-endpoints/3/deliveries");

using var response = await http.SendAsync(request);
Console.WriteLine($"{(int)response.StatusCode} {await response.Content.ReadAsStringAsync()}");

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("GET", os.Getenv("FLUX_BASE_URL")+"/api/v1/webhook-endpoints/3/deliveries", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "ApiKey "+os.Getenv("FLUX_API_KEY"))

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	out, _ := io.ReadAll(resp.Body)
	fmt.Println(resp.StatusCode, string(out))
}

Responses

200 OK

{
  "data": [
    {
      "id": 99001,
      "eventId": "evt_01JC8Z5T6Q1W3M4N5P6R7S8T9V",
      "eventType": "invoice.paid",
      "status": "delivered",
      "attempts": 1,
      "lastStatusCode": 200,
      "lastError": null,
      "nextAttemptAt": null,
      "lastAttemptAt": "2026-11-03T14:02:05",
      "deliveredAt": "2026-11-03T14:02:05",
      "createdAt": "2026-11-03T14:02:04"
    }
  ],
  "nextCursor": null,
  "hasMore": false
}

4 possible errors

Status	Code	When
`404`	`not_found`	Unknown id, or an id that belongs to another organization.
`401`	`unauthorized`	No API key, an unknown key or a revoked key.
`403`	`insufficient_scope`	The key lacks the scope. `details` names it: `{ "required": "invoices:write" }`.
`429`	`rate_limited`	Too many requests for this key. Wait for the `Retry-After` seconds.

Redeliver#

POST/api/v1/webhook-deliveries/{id}/redeliverwebhooks:manage

Sends a delivery again now, whatever its status, keeping its attempt history. Use it for dead deliveries once your endpoint is fixed.

Path parameters

Field	Description
idinteger (64-bit)	required The delivery's id, from the delivery log.

Request

curl -X POST "$FLUX_BASE_URL/api/v1/webhook-deliveries/99001/redeliver" \
  -H "Authorization: ApiKey $FLUX_API_KEY"

// Node.js 18+ (built-in fetch). Save as an .mjs file.
const response = await fetch(`${process.env.FLUX_BASE_URL}/api/v1/webhook-deliveries/99001/redeliver`, {
  method: "POST",
  headers: {
    Authorization: `ApiKey ${process.env.FLUX_API_KEY}`,
  },
});
console.log(response.status, await response.text());

import os

import requests

response = requests.post(
    f"{os.environ['FLUX_BASE_URL']}/api/v1/webhook-deliveries/99001/redeliver",
    headers={"Authorization": f"ApiKey {os.environ['FLUX_API_KEY']}"},
    timeout=30,
)
print(response.status_code, response.text)

<?php
$ch = curl_init(getenv('FLUX_BASE_URL') . '/api/v1/webhook-deliveries/99001/redeliver');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'Authorization: ApiKey ' . getenv('FLUX_API_KEY'),
    ],
    CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), ' ', $response, PHP_EOL;

using System.Net.Http.Headers;

var baseUrl = Environment.GetEnvironmentVariable("FLUX_BASE_URL");
using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("ApiKey", Environment.GetEnvironmentVariable("FLUX_API_KEY"));

using var request = new HttpRequestMessage(HttpMethod.Post, $"{baseUrl}/api/v1/webhook-deliveries/99001/redeliver");

using var response = await http.SendAsync(request);
Console.WriteLine($"{(int)response.StatusCode} {await response.Content.ReadAsStringAsync()}");

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("POST", os.Getenv("FLUX_BASE_URL")+"/api/v1/webhook-deliveries/99001/redeliver", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "ApiKey "+os.Getenv("FLUX_API_KEY"))

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	out, _ := io.ReadAll(resp.Body)
	fmt.Println(resp.StatusCode, string(out))
}

Responses

202 Accepted

No body.

4 possible errors

Status	Code	When
`404`	`not_found`	Unknown id, or an id that belongs to another organization.
`401`	`unauthorized`	No API key, an unknown key or a revoked key.
`403`	`insufficient_scope`	The key lacks the scope. `details` names it: `{ "required": "invoices:write" }`.
`429`	`rate_limited`	Too many requests for this key. Wait for the `Retry-After` seconds.