API reference

Webhook Endpoints

You can configure webhook endpoints via the API to be notified about events that happen in your Stripe account or connected accounts. Most users configure webhooks from the dashboard, which provides a user interface for registering and testing your webhook endpoints. Related guide: Setting up webhooks

Knox answers these operations with the same requests and responses as Stripe's API. Authenticate with your secret key, Authorization: Bearer sk_test_..., from your server, and send form-encoded bodies. Test mode only: live processing is currently disabled.

Create a webhook endpoint

POST/v1/webhook_endpoints

A webhook endpoint must have a url and a list of enabled_events. You may optionally specify the Boolean connect parameter. If set to true, then a Connect webhook endpoint that notifies the specified url about events from all connected accounts is created; otherwise an account webhook endpoint that notifies the specified url only about events from your account is created. You can also create webhook endpoints in the webhooks settings section of the Dashboard.

Body parameters

  • enabled_eventsarray of stringsRequired

    The list of events to enable for this endpoint. You may specify ['*'] to enable all events, except those that require explicit selection.

  • urlstringRequired

    The URL of the webhook endpoint.

  • api_versionstring

    Events sent to this endpoint will be generated with this Stripe Version instead of your account's default Stripe Version.

    Possible values
    • 2026-03-25.dahlia
    • 2026-04-22.dahlia
    • 2026-05-27.dahlia
    • 2026-06-24.dahlia
    • 2026-07-29.dahlia
    • 2026-08-26.dahlia
  • connectboolean

    Whether this endpoint should receive events from connected accounts (true), or from your account (false). Defaults to false.

  • descriptionstring

    An optional description of what the webhook is used for.

  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • metadataobject

    Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

Returns

The webhook_endpoint object.

POST /v1/webhook_endpoints
curl https://api.knoxapi.com/v1/webhook_endpoints \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  -d "enabled_events[]=charge.failed" \
  -d url=https://example.com/my/webhook/endpoint
Response
{
  "api_version": null,
  "application": null,
  "created": 1234567890,
  "description": "This is my webhook, I like it a lot",
  "enabled_events": [
    "charge.failed",
    "charge.succeeded"
  ],
  "id": "we_1Pgc6yB7WZ01zgkWzAudq4eU",
  "livemode": false,
  "metadata": {},
  "object": "webhook_endpoint",
  "status": "enabled",
  "url": "https://example.com/my/webhook/endpoint"
}

List all webhook endpoints

GET/v1/webhook_endpoints

Returns a list of your webhook endpoints.

Query parameters

  • ending_beforestring

    A cursor for use in pagination. ending_before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_bar, your subsequent call can include ending_before=obj_bar in order to fetch the previous page of the list.

  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • limitinteger

    A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.

  • starting_afterstring

    A cursor for use in pagination. starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include starting_after=obj_foo in order to fetch the next page of the list.

Returns

A list of webhook_endpoint objects.

GET /v1/webhook_endpoints
curl -G https://api.knoxapi.com/v1/webhook_endpoints \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  --data-urlencode limit=3
Response
{
  "object": "list",
  "url": "/v1/webhook_endpoints",
  "has_more": false,
  "data": [
    {
      "api_version": null,
      "application": null,
      "created": 1234567890,
      "description": "This is my webhook, I like it a lot",
      "enabled_events": [
        "charge.failed",
        "charge.succeeded"
      ],
      "id": "we_1Pgc6yB7WZ01zgkWzAudq4eU",
      "livemode": false,
      "metadata": {},
      "object": "webhook_endpoint",
      "status": "enabled",
      "url": "https://example.com/my/webhook/endpoint"
    }
  ]
}

Update a webhook endpoint

POST/v1/webhook_endpoints/{webhook_endpoint}

Updates the webhook endpoint. You may edit the url, the list of enabled_events, and the status of your endpoint.

Path parameters

  • webhook_endpointstringRequired

Body parameters

  • descriptionstring

    An optional description of what the webhook is used for.

  • disabledboolean

    Disable the webhook endpoint if set to true.

  • enabled_eventsarray of strings

    The list of events to enable for this endpoint. You may specify ['*'] to enable all events, except those that require explicit selection.

  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • metadataobject

    Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

  • urlstring

    The URL of the webhook endpoint.

Returns

The webhook_endpoint object.

POST /v1/webhook_endpoints/{webhook_endpoint}
curl https://api.knoxapi.com/v1/webhook_endpoints/we_1Pgc6yB7WZ01zgkWzAudq4eU \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  -d "metadata[order_id]=6735"
Response
{
  "api_version": null,
  "application": null,
  "created": 1234567890,
  "description": "This is my webhook, I like it a lot",
  "enabled_events": [
    "charge.failed",
    "charge.succeeded"
  ],
  "id": "we_1Pgc6yB7WZ01zgkWzAudq4eU",
  "livemode": false,
  "metadata": {},
  "object": "webhook_endpoint",
  "status": "enabled",
  "url": "https://example.com/my/webhook/endpoint"
}

Retrieve a webhook endpoint

GET/v1/webhook_endpoints/{webhook_endpoint}

Retrieves the webhook endpoint with the given ID.

Path parameters

  • webhook_endpointstringRequired

Query parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The webhook_endpoint object.

GET /v1/webhook_endpoints/{webhook_endpoint}
curl https://api.knoxapi.com/v1/webhook_endpoints/we_1Pgc6yB7WZ01zgkWzAudq4eU \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "api_version": null,
  "application": null,
  "created": 1234567890,
  "description": "This is my webhook, I like it a lot",
  "enabled_events": [
    "charge.failed",
    "charge.succeeded"
  ],
  "id": "we_1Pgc6yB7WZ01zgkWzAudq4eU",
  "livemode": false,
  "metadata": {},
  "object": "webhook_endpoint",
  "status": "enabled",
  "url": "https://example.com/my/webhook/endpoint"
}

Delete a webhook endpoint

DELETE/v1/webhook_endpoints/{webhook_endpoint}

You can also delete webhook endpoints via the webhook endpoint management page of the Stripe dashboard.

Path parameters

  • webhook_endpointstringRequired

Returns

The deleted_webhook_endpoint object.

DELETE /v1/webhook_endpoints/{webhook_endpoint}
curl -X DELETE https://api.knoxapi.com/v1/webhook_endpoints/we_1Pgc6yB7WZ01zgkWzAudq4eU \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "deleted": true,
  "id": "we_1Pgc6yB7WZ01zgkWzAudq4eU",
  "object": "webhook_endpoint"
}

Operations and schemas come from the pinned Stripe OpenAPI specification (MIT); response examples from its fixtures. Nested object definitions and enums are in the complete specification.