Docs

API reference / Webhooks

List webhook endpoints

GET/v1/webhook-endpoints

API key requiredCursor pagination

Webhook endpoints of your project for the key’s environment, newest first. Secrets are never returned.

Authentication#

Send a secret API key as Authorization: Bearer <key>. Both tp_test_… and tp_live_… keys work; the key decides which environment you read and write. See Authentication.

Parameters#

Query

Query parameters
NameTypeDescription
limitintegerNumber of items per page (1 to 100).Default 20
starting_afterstringCursor: id of the last item of the previous page.

See Pagination for how to walk through pages.

Responses#

200Page of webhook endpoints.

Headers

  • X-Request-Id Request identifier.
  • X-RateLimit-Limit Quota of the current window.
  • X-RateLimit-Remaining Requests remaining in the window.
  • X-RateLimit-Reset Seconds before the quota renews.

Body

  • objectstringrequired

    always "list"

    Example "list"

  • dataarray of WebhookEndpointrequired
    • idstringrequired

      Opaque identifier.

      Example "0b2c8f6e-41f9-4c0a-8d55-6f6a3c1d9e21"

    • objectstringrequired

      always "webhook_endpoint"

      Example "webhook_endpoint"

    • urlstringrequired

      HTTPS URL that receives the events.

      Example "https://example.com/webhooks/tilt-pay"

    • descriptionstring | nullrequired

      Free-form label.

      Example "Production backend"

    • event_typesarray of stringrequired

      Event types delivered to this endpoint, or ["*"] for all of them. Duplicates are removed.

      One ofuser.createduser.suspendeduser.unsuspendedkyc.approvedkyc.rejectedtransaction.receivedtransaction.completedwithdrawal.completedwithdrawal.failed*

    • enabledbooleanrequired

      The endpoint receives events.

      Example true

    • disabled_reasonstring | nullrequired

      manual when you disabled it, consecutive_failures when Tilt Pay disabled it after 20 failed attempts in a row.

      One ofmanualconsecutive_failures

    • consecutive_failuresintegerrequired

      Failed attempts in a row (reset by a success).

      Example 0

    • secret_last4stringrequired

      Last four characters of the current signing secret.

      Example "x9Yz"

    • previous_secret_expires_atstring | nullrequired

      During a rotation, until when the previous secret also signs events.

      format: date-time

      Example "2026-10-08T09:30:00.000Z"

    • livemodebooleanrequired

      true for a live endpoint, false for a sandbox endpoint.

      Example false

    • created_atstringrequired

      Creation date.

      format: date-time

      Example "2026-10-08T09:30:00.000Z"

    • updated_atstringrequired

      Last update.

      format: date-time

      Example "2026-10-08T09:30:00.000Z"

  • has_morebooleanrequired

    More items remain: call again with starting_after set to the id of the last item.

    Example false

Example 200 response
{
  "object": "list",
  "data": [
    {
      "id": "0b2c8f6e-41f9-4c0a-8d55-6f6a3c1d9e21",
      "object": "webhook_endpoint",
      "url": "https://example.com/webhooks/tilt-pay",
      "description": "Production backend",
      "event_types": [
        "*"
      ],
      "enabled": true,
      "disabled_reason": null,
      "consecutive_failures": 0,
      "secret_last4": "x9Yz",
      "previous_secret_expires_at": null,
      "livemode": false,
      "created_at": "2026-10-08T09:30:00.000Z",
      "updated_at": "2026-10-08T09:30:00.000Z"
    }
  ],
  "has_more": false
}
400Invalid request (malformed JSON, unknown cursor, invalid Idempotency-Key header).

Example: invalid_cursor

Example 400 response
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_cursor",
    "message": "starting_after: unknown cursor",
    "request_id": "0b2c8f6e-41f9-4c0a-8d55-6f6a3c1d9e21"
  }
}
401Missing, invalid or revoked API key.

Example: missing_api_key

Example 401 response
{
  "error": {
    "type": "authentication_error",
    "code": "missing_api_key",
    "message": "Provide your API key as \"Authorization: Bearer <key>\"",
    "request_id": "0b2c8f6e-41f9-4c0a-8d55-6f6a3c1d9e21"
  }
}

Example: invalid_api_key

Example 401 response
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "The API key is invalid",
    "request_id": "0b2c8f6e-41f9-4c0a-8d55-6f6a3c1d9e21"
  }
}

Example: api_key_revoked

Example 401 response
{
  "error": {
    "type": "authentication_error",
    "code": "api_key_revoked",
    "message": "This API key has been revoked",
    "request_id": "0b2c8f6e-41f9-4c0a-8d55-6f6a3c1d9e21"
  }
}
403Organization suspended, live access not enabled, or sandbox-only route.

Example: organization_suspended

Example 403 response
{
  "error": {
    "type": "permission_error",
    "code": "organization_suspended",
    "message": "Your organization is suspended. Contact Tilt Pay support.",
    "request_id": "0b2c8f6e-41f9-4c0a-8d55-6f6a3c1d9e21"
  }
}

Example: live_not_enabled

Example 403 response
{
  "error": {
    "type": "permission_error",
    "code": "live_not_enabled",
    "message": "Live access has not been enabled for your organization yet",
    "request_id": "0b2c8f6e-41f9-4c0a-8d55-6f6a3c1d9e21"
  }
}

Example: sandbox_only

Example 403 response
{
  "error": {
    "type": "permission_error",
    "code": "sandbox_only",
    "message": "This route is only available with a sandbox API key",
    "request_id": "0b2c8f6e-41f9-4c0a-8d55-6f6a3c1d9e21"
  }
}
422Invalid parameter, or Idempotency-Key reused with a different body.

Example: validation_error

Example 422 response
{
  "error": {
    "type": "invalid_request_error",
    "code": "validation_error",
    "message": "phone: has an invalid format",
    "request_id": "0b2c8f6e-41f9-4c0a-8d55-6f6a3c1d9e21"
  }
}

Example: idempotency_key_reuse

Example 422 response
{
  "error": {
    "type": "idempotency_error",
    "code": "idempotency_key_reuse",
    "message": "This Idempotency-Key was already used with a different request",
    "request_id": "0b2c8f6e-41f9-4c0a-8d55-6f6a3c1d9e21"
  }
}
429Rate limit exceeded. Retry after the Retry-After delay (seconds).

Example: rate_limit_exceeded

Example 429 response
{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Slow down and retry after the delay in Retry-After.",
    "request_id": "0b2c8f6e-41f9-4c0a-8d55-6f6a3c1d9e21"
  }
}
500Internal error. Retry; give request_id to support if it persists.

Example: internal_error

Example 500 response
{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "Internal server error",
    "request_id": "0b2c8f6e-41f9-4c0a-8d55-6f6a3c1d9e21"
  }
}

Headers on every response

  • X-Request-Id Identifier of the request, also present in error bodies. Give it to support.
  • X-API-Version Version of the API that answered.
  • X-RateLimit-Limit / -Remaining / -Reset Quota of your key for the current window. See Rate limits.

Errors#

Errors share one format, described in Errors. Branch your code on error.code.

Errors this route can return
StatusCodeMeaning
400invalid_cursorUnknown starting_after cursor.
401missing_api_keyMissing, invalid or revoked API key.
401invalid_api_keyMissing, invalid or revoked API key.
401api_key_revokedMissing, invalid or revoked API key.
403organization_suspendedOrganization suspended, live access not enabled, or sandbox-only route.
403live_not_enabledOrganization suspended, live access not enabled, or sandbox-only route.
403sandbox_onlyOrganization suspended, live access not enabled, or sandbox-only route.
422validation_errorInvalid parameter, or Idempotency-Key reused with a different body.
422idempotency_key_reuseInvalid parameter, or Idempotency-Key reused with a different body.
429rate_limit_exceededRate limit exceeded. Retry after the Retry-After delay (seconds).
500internal_errorInternal error. Retry; give request_id to support if it persists.