Skip to content
AutoPayKe Docs
Get started

Webhook endpoints

Manage where we send events, from code. The Console does the same; use whichever suits your deploys.

GETList endpoints/api/v1/webhook-endpointsPOSTCreate an endpoint/api/v1/webhook-endpointsGETGet an endpoint/api/v1/webhook-endpoints/{id}PATCHUpdate an endpoint/api/v1/webhook-endpoints/{id}DELDelete an endpoint/api/v1/webhook-endpoints/{id}POSTRoll the signing secret/api/v1/webhook-endpoints/{id}/roll-secretGETList deliveries/api/v1/webhook-endpoints/{id}/deliveries

Endpoints belong to the key's environment: a test key manages test endpoints, which only receive test events.

Send your API key as Authorization: Bearer apk_test_… (sandbox) or apk_live_… (live). Each endpoint lists the scope the key needs. See API keys.

List endpoints

GET/api/v1/webhook-endpoints
API keywebhooks:write

Your endpoints in this environment, with their success rate over the last 7 days.

Request
curl "https://api.autopayke.com/api/v1/webhook-endpoints" \
  -H "Authorization: Bearer $AUTOPAYKE_API_KEY"
Response200 application/json
{
  "ok": true,
  "data": {
    "object": "list",
    "data": [
      {
        "id": "1d7c3b5e-2a49-4f86-9a0e-6c2b8d4f1e73",
        "url": "https://api.example.com/webhooks/autopayke",
        "description": "Production listener",
        "environment": "test",
        "events": [
          "payout.succeeded",
          "payout.failed",
          "payout.reversed"
        ],
        "status": "enabled",
        "disabledReason": null,
        "failingSince": null,
        "secretPrefix": "whsec_9xKq2LmZ",
        "createdAt": "2026-11-03T09:10:00.000Z",
        "successRate7d": 0.99,
        "deliveries7d": 412
      }
    ]
  }
}

Create an endpoint

POST/api/v1/webhook-endpoints
API keywebhooks:write

Start sending events to a URL. The response includes the signing secret, once.

Body (JSON)
  • urlstringrequired

    An https URL on the public internet, up to 2048 characters. Private, local and link-local addresses are refused.

  • eventsstring[]required

    The event types to send, or ["*"] for all, including types we add later.

  • descriptionstringoptional

    Up to 200 characters.

Request
curl -X POST "https://api.autopayke.com/api/v1/webhook-endpoints" \
  -H "Authorization: Bearer $AUTOPAYKE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.example.com/webhooks/autopayke",
    "events": [
      "payout.succeeded",
      "payout.failed",
      "payout.reversed"
    ],
    "description": "Production listener"
  }'
Response201 application/json
{
  "ok": true,
  "data": {
    "id": "1d7c3b5e-2a49-4f86-9a0e-6c2b8d4f1e73",
    "url": "https://api.example.com/webhooks/autopayke",
    "description": "Production listener",
    "environment": "test",
    "events": [
      "payout.succeeded",
      "payout.failed",
      "payout.reversed"
    ],
    "status": "enabled",
    "disabledReason": null,
    "failingSince": null,
    "secretPrefix": "whsec_9xKq2LmZ",
    "createdAt": "2026-11-03T09:10:00.000Z",
    "secret": "whsec_9xKq2LmZp4Rt7Vb1Nc8Yw3Jd6Hf0Gs5A"
  }
}
Errors
VALIDATION_ERROR

Plus the key and rate errors any keyed call can return.

  • Store secret in your secret manager. You can roll it, but we won't show this one again through the API (the Console can reveal it after a PIN check).

Get an endpoint

GET/api/v1/webhook-endpoints/{id}
API keywebhooks:write

One endpoint. failingSince is set while deliveries keep failing; after 3 days we disable it and set disabledReason.

Path parameters
  • idstringrequired

    Endpoint id.

Request
curl "https://api.autopayke.com/api/v1/webhook-endpoints/1d7c3b5e-2a49-4f86-9a0e-6c2b8d4f1e73" \
  -H "Authorization: Bearer $AUTOPAYKE_API_KEY"
Response200 application/json
{
  "ok": true,
  "data": {
    "id": "1d7c3b5e-2a49-4f86-9a0e-6c2b8d4f1e73",
    "url": "https://api.example.com/webhooks/autopayke",
    "description": "Production listener",
    "environment": "test",
    "events": [
      "payout.succeeded",
      "payout.failed",
      "payout.reversed"
    ],
    "status": "enabled",
    "disabledReason": null,
    "failingSince": null,
    "secretPrefix": "whsec_9xKq2LmZ",
    "createdAt": "2026-11-03T09:10:00.000Z"
  }
}
Errors
NOT_FOUND

Plus the key and rate errors any keyed call can return.

Update an endpoint

PATCH/api/v1/webhook-endpoints/{id}
API keywebhooks:write

Change the URL, the events or the description, or turn it off and on. Turning a disabled endpoint back on clears its failure state.

Path parameters
  • idstringrequired

    Endpoint id.

Body (JSON)
  • urlstringoptional

    New https URL.

  • eventsstring[]optional

    Replaces the list.

  • descriptionstringoptional

    Up to 200 characters.

  • enabledbooleanoptional

    false stops deliveries; true starts them again.

Request
curl -X PATCH "https://api.autopayke.com/api/v1/webhook-endpoints/1d7c3b5e-2a49-4f86-9a0e-6c2b8d4f1e73" \
  -H "Authorization: Bearer $AUTOPAYKE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true
  }'
Response200 application/json
{
  "ok": true,
  "data": {
    "id": "1d7c3b5e-2a49-4f86-9a0e-6c2b8d4f1e73",
    "url": "https://api.example.com/webhooks/autopayke",
    "description": "Production listener",
    "environment": "test",
    "events": [
      "payout.succeeded",
      "payout.failed",
      "payout.reversed"
    ],
    "status": "enabled",
    "disabledReason": null,
    "failingSince": null,
    "secretPrefix": "whsec_9xKq2LmZ",
    "createdAt": "2026-11-03T09:10:00.000Z"
  }
}
Errors
VALIDATION_ERRORNOT_FOUND

Plus the key and rate errors any keyed call can return.

Delete an endpoint

DEL/api/v1/webhook-endpoints/{id}
API keywebhooks:write

Stop sending to this endpoint for good. Deliveries waiting for a retry are dropped; the events stay readable at GET /api/v1/events.

Path parameters
  • idstringrequired

    Endpoint id.

Request
curl -X DELETE "https://api.autopayke.com/api/v1/webhook-endpoints/1d7c3b5e-2a49-4f86-9a0e-6c2b8d4f1e73" \
  -H "Authorization: Bearer $AUTOPAYKE_API_KEY"
Response200 application/json
{
  "ok": true,
  "data": {
    "id": "1d7c3b5e-2a49-4f86-9a0e-6c2b8d4f1e73",
    "deleted": true
  }
}
Errors
NOT_FOUND

Plus the key and rate errors any keyed call can return.

Roll the signing secret

POST/api/v1/webhook-endpoints/{id}/roll-secret
API keywebhooks:write

Issue a new signing secret. The old one stops at once, so deploy code that accepts both before you roll, then remove the old one.

Path parameters
  • idstringrequired

    Endpoint id.

Request
curl -X POST "https://api.autopayke.com/api/v1/webhook-endpoints/1d7c3b5e-2a49-4f86-9a0e-6c2b8d4f1e73/roll-secret" \
  -H "Authorization: Bearer $AUTOPAYKE_API_KEY"
Response200 application/json
{
  "ok": true,
  "data": {
    "secret": "whsec_Lm4Nx6Rt1Vb9Yc3Jk8Qw2Zp7Fq2mZx7L"
  }
}
Errors
NOT_FOUND

Plus the key and rate errors any keyed call can return.

List deliveries

GET/api/v1/webhook-endpoints/{id}/deliveries
API keywebhooks:write

Recent delivery attempts to this endpoint: what we sent, what you answered and when we'll retry.

Path parameters
  • idstringrequired

    Endpoint id.

Request
curl "https://api.autopayke.com/api/v1/webhook-endpoints/1d7c3b5e-2a49-4f86-9a0e-6c2b8d4f1e73/deliveries" \
  -H "Authorization: Bearer $AUTOPAYKE_API_KEY"
Response200 application/json
{
  "ok": true,
  "data": {
    "object": "list",
    "data": [
      {
        "id": "8c1e5a2f-9b3d-4f7e-a6c0-2d8b4e1f7a93",
        "eventId": "evt_3Jk8Qw2Zp7Lm4Nx6Rt1Vb9Yc",
        "eventType": "payout.succeeded",
        "attempt": 2,
        "status": "failed",
        "responseCode": 500,
        "responseBody": "Internal Server Error",
        "error": null,
        "durationMs": 312,
        "nextRetryAt": "2026-11-03T09:16:06.000Z",
        "deliveredAt": null,
        "createdAt": "2026-11-03T09:10:06.000Z"
      }
    ]
  }
}
Response fields
  • statusstring

    pending (queued), succeeded (you answered 2xx), failed (will retry), abandoned (we gave up after 3 days).

  • attemptinteger

    1 for the first try.

  • responseCodeinteger | null

    Your HTTP status, or null when we couldn't connect.

  • responseBodystring | null

    The start of your response body, for debugging.

  • errorstring | null

    Why we couldn't deliver (timeout, DNS, TLS, refused URL).

  • nextRetryAtstring | null

    When the next attempt is due.

Errors
NOT_FOUND

Plus the key and rate errors any keyed call can return.