Skip to content
Connect an agent

Webhooks

Add a webhook endpoint

Flung POSTs each subscribed event to the URL, signed to the Standard Webhooks spec with the returned secret, and retries failures with backoff for about 15 hours.

POST/v1/webhook-endpoints

TL;DR

QuestionAnswer
What does it do?Add a webhook endpoint.
What does it need?An API key or an OAuth access token.
What does it take?A JSON body with the fields below, and idempotency-key in a header.
What does it return?Status 201 with a body of type CreatedWebhookEndpoint.
In the SDK?flung.webhookEndpoints.create()
What can go wrong?401 Missing, unknown, revoked or expired API key; 422 The request failed validation; 429 Too many requests for this credential; wait for retry-after seconds. Every failure has the same error shape.

Example

bash
curl -X POST 'https://api.flung.dev/v1/webhook-endpoints' \  --header "Authorization: Bearer $FLUNG_API_KEY" \  --header 'Content-Type: application/json' \  --header "Idempotency-Key: $(uuidgen)" \  --data '{  "url": "https://example.com/webhooks/flung",  "events": [    "post.published",    "post.failed"  ]}'

A successful answer looks like this:

json
{  "id": "whe_aaaaaaaaaaaaaaaaaaaaaaaa",  "url": "string",  "events": [    "string"  ],  "enabled": true,  "createdAt": "2026-11-01T09:00:00.000Z",  "secret": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw"}

Header parameters

FieldTypeRequiredDescription
idempotency-keystringnoAny unique string, such as a UUID. A retry with the same key and body within 24 hours gets the first answer instead of running again.

Request body

The body has the type an object, with the fields below.

FieldTypeRequiredDescription
urlstringyesat most 2048 characters.
eventsWebhookEvent[]yes

Responses

StatusMeaningBody
201The endpoint, with its signing secret.CreatedWebhookEndpoint
401Missing, unknown, revoked or expired API key.Error
422The request failed validation.Error
429Too many requests for this credential; wait for retry-after seconds.Error

Response body

A 201 answer has the type CreatedWebhookEndpoint.

FieldTypeRequiredDescription
idstringyes
urlstringyes
eventsstring[]yes
enabledbooleanyes
createdAtstringyes
secretstringyesThe signing secret (Standard Webhooks, whsec_...). Shown only in this response; store it now.

See also

DocWhy
API referenceEvery endpoint
SchemasEvery request and response type
ErrorsEvery error code and what to do about it