Webhook endpoints

List webhook endpoints

Lists the webhook endpoints registered for your organization.

GET

GET/organizations/{organizationId}/webhook-endpoints

curl -s "$AVVIO_BASE_URL/organizations/$organizationId/webhook-endpoints" \
  -H "x-api-key: $AVVIO_API_KEY"

const organizationId = '<organizationId>';

const res = await fetch(`${process.env.AVVIO_BASE_URL}/organizations/${organizationId}/webhook-endpoints`, {
  headers: {
    'x-api-key': process.env.AVVIO_API_KEY,
  },
});
console.log(res.status, await res.json());

import os
import requests

organizationId = "<organizationId>"

res = requests.get(
    f"{os.environ['AVVIO_BASE_URL']}/organizations/{organizationId}/webhook-endpoints",
    headers={
        "x-api-key": os.environ["AVVIO_API_KEY"],
    },
)
print(res.status_code, res.json())

200OK

[
  {
    "id": "cmf3k2xe80006q8b7d2f4g6hj",
    "url": "https://example.com/hooks/avvio",
    "events": [
      "payout.completed",
      "payout.failed"
    ],
    "disabledAt": null,
    "disabledReason": null,
    "consecutiveFailures": 0,
    "lastSuccessAt": "2026-09-03T10:00:04.000Z",
    "lastFailureAt": null,
    "createdAt": "2026-08-20T13:58:02.000Z"
  }
]

{
  "type": "UNAUTHORIZED",
  "status": 401,
  "detail": "Invalid API key",
  "resolution": "Check the API key was copied whole and has not been revoked.",
  "requestId": "req-9bz",
  "message": "Invalid API key",
  "statusCode": 401
}

{
  "type": "FORBIDDEN",
  "status": 403,
  "detail": "This API key cannot access that organization",
  "resolution": "This key is scoped to a different organization.",
  "requestId": "req-9d0",
  "message": "This API key cannot access that organization",
  "statusCode": 403
}

{
  "type": "RATE_LIMITED",
  "status": 429,
  "detail": "ThrottlerException: Too Many Requests",
  "resolution": "Back off and retry after the Retry-After interval.",
  "requestId": "req-9e1",
  "message": "ThrottlerException: Too Many Requests",
  "statusCode": 429
}

Path parameters

organizationIdstringRequired
Your organization id.

Behavior

Read-only. Registering, pausing, deleting, rotating the secret of or replaying an endpoint is a dashboard action and cannot be done with an API key, because a credential that could repoint its own webhook URL could quietly redirect every payout notification you receive. The dashboard routes, for completeness: POST .../webhook-endpoints/{endpointId}/rotate-secret (the old secret keeps signing beside the new one for 24 hours, so nothing in flight drops) and POST .../webhook-endpoints/{endpointId}/deliveries/replay (re-fires up to 1,000 dead deliveries in a from/to window under their original event ids, so your dedupe still holds).

The health fields are how you see an endpoint dying without asking us: consecutiveFailures counts exhausted retry ladders since the last success, and after three of them with no success for five days we disable the endpoint (disabledReason: auto_disabled_after_failures), email your organization's owners, and deliver webhook_endpoint.disabled to your other endpoints whose events list is empty. It cannot be named in events, so an endpoint with an explicit list never receives it.

The signing secret is never returned here. You are shown it once, when the endpoint is created or rotated.

Responses

200Registered endpoints

Body

idstringRequired
urlstring<uri>Required
eventsarray of stringRequired
Empty means every payout-side type (payout, approval, batch and endpoint lifecycle), but not checkout_payment.*, which is delivered only when named here.
disabledAtstring<date-time> | nullRequired
Non-null while the endpoint is paused or auto-disabled.
disabledReasonstring | nullRequired
Allowed values:paused_by_ownerauto_disabled_after_failuresnull
consecutiveFailuresintegerRequired
Retry ladders exhausted since the last accepted delivery. Reset to 0 on success and on re-enable.
lastSuccessAtstring<date-time> | nullRequired
lastFailureAtstring<date-time> | nullRequired
createdAtstring<date-time>Required

Errors

401
The key was refused. Nothing ran.
- UNAUTHORIZED: missing, invalid or revoked, or a key on a route that does not accept one.
- KEY_EXPIRED: the key passed the expiry it was issued with. Issue a new one; an expired key cannot be rotated.
- KEY_IP_NOT_ALLOWED: the key is pinned to source addresses and this request came from another.
403
A valid key that may not make this call. Nothing ran.
- FORBIDDEN: the key belongs to a different organization.
- ACCOUNT_BLOCKED: API access for your organization is suspended.
- DEVELOPER_FEATURE_DISABLED: developer tools (webhook endpoints) are off for your organization. GET /policy lists developer in features when they are on.
429
Too many requests. The default ceiling is 100 requests per minute per API credential on a 60-second window. High-volume payout and reconciliation routes declare a 600/minute override, and batch submission a 30/minute ceiling. A separate 2,000/minute per-source-IP abuse ceiling always applies.

Obey Retry-After; it is in seconds and is authoritative. A 429 means the request was refused before the handler ran. Retry reads normally; retry an idempotent mutation with its same Idempotency-Key.

Error body · Error

typestringRequired
Stable machine-readable code.
detailstringRequired
What went wrong, in a sentence. Always a string, so detail.toLowerCase() is safe.
More
This is the field to read on BAD_REQUEST and PROVIDER_REJECTED, where the type alone does not name the condition.
messagestringRequired
The same text as detail, kept for integrations written before detail existed. Read detail.
resolutionstringOptional
What to do about it, when there is a specific answer. It is not on every error (it is absent on BAD_REQUEST, NOT_FOUND, PAYOUT_NOT_CANCELABLE and DESTINATION_ACCOUNT_NOT_FOUND), so treat it as optional and fall back to detail.
statusintegerRequired
HTTP status, repeated in the body.
statusCodeintegerRequired
The same value as status, kept for integrations written before status existed. Read status.
requestIdstringRequired
Quote this to support and we can find the exact request. Also sent as the x-request-id response header, which is the only place it appears on a successful response. Success bodies do not carry it. Send your own x-request-id on the request and we use it, so your trace and ours share one identifier; otherwise we mint one.
errorsarray of stringOptional
Present on VALIDATION_ERROR; names each field that failed.
originalIdempotencyKeystringOptional
On DUPLICATE_REQUEST_DETECTED only. Send the request again with this to receive the original payout instead of making a second one. Without it there is no way to recover except by risking a double payment.
originalPayoutIdstringOptional
On DUPLICATE_REQUEST_DETECTED only. The payout the first request created.
originalBatchIdstringOptional
On a batch DUPLICATE_REQUEST_DETECTED. The run the first request created.
originalRequestIdstringOptional
On a 409 PAYOUT_OUTCOME_UNKNOWN replay. The requestId of the call whose outcome is unknown; quote it to support.
existingRecipientIdstringOptional
On BANK_ACCOUNT_ALREADY_LINKED. The recipient in your organization that already holds this account.
existingMethodIdstringOptional
On BANK_ACCOUNT_ALREADY_LINKED. The payment method on that recipient.

Branch on type, never on the status or the message. Every error type is listed with what to do about it.

Avvio Partner Payouts · Webhook endpoints · operation listWebhookEndpoints

Try it: List webhook endpoints

GET https://api.avvio.xyz/business/api/v1/organizations/{organizationId}/webhook-endpoints

API key Required

Test keys only. Sent as x-api-key through this site's proxy to the Avvio API, never saved, and cleared when you close this dialog.

organizationId pathRequired

Was this page helpful?