Webhooks

Manage webhook endpoints. Frame sends real-time event notifications to your registered endpoints as objects on your account change state.

List webhook endpoints

Returns a list of webhook endpoints configured for the authenticated merchant. You can configure webhook endpoints via the API to be notified about events that happen in your Frame account.

Most users configure webhooks from the dashboard, which provides a user interface for registering your webhook endpoints.

Query parameters
pageintegeroptional

Page number for pagination.

per_pageintegeroptional

Number of results per page.

Returns

A paginated list of webhook endpoints.

GET/v1/webhook_endpoints
curl --request GET \
  --url https://api.framepayments.com/v1/webhook_endpoints \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "meta": {
    "page": 1,
    "url": "/v1/webhook_endpoints",
    "has_more": false,
    "prev": null,
    "next": null
  },
  "data": []
}

Create webhook endpoint

Creates a webhook endpoint. Provide an HTTPS URL and the list of event codes you want delivered. The response includes the signing secret; surface it to the user once — it can be rotated later via /v1/webhook_endpoints/{id}/rotate_secret.

Body parameters
urlstringrequired

HTTPS URL Frame will POST events to.

descriptionstringoptional

Optional human-readable description.

event_codesarrayrequired

List of event codes to subscribe to. Must be drawn from the canonical event-code catalog.

Returns

Returns the created webhook endpoint, including its signing secret.

POST/v1/webhook_endpoints
curl --request POST \
  --url https://api.framepayments.com/v1/webhook_endpoints \
  --header 'Authorization: Bearer API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "url": null,
  "event_codes": [
    null
  ]
}'
RESPONSE
{
  "id": "2fa88629-a79a-4b52-bb9f-e509bbc914d6",
  "description": "Test",
  "livemode": false,
  "event_codes": [
    "charge.captured"
  ],
  "secret": "5RFTjJwttnEecPea5P8aRXaHPJ2PtAQ7",
  "status": "active",
  "url": "https://example.com/hook",
  "created": 1781115893,
  "updated": 1781115893,
  "object": "webhook_endpoint"
}

Retrieve webhook endpoint

Retrieves a webhook endpoint by ID.

Path parameters
idstringrequired

Unique identifier for the webhook endpoint.

Returns

Returns the webhook endpoint.

GET/v1/webhook_endpoints/{id}
curl --request GET \
  --url https://api.framepayments.com/v1/webhook_endpoints/a70cd72f-e74a-40f2-96a2-3f60714aac4a \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "id": "6576a117-6f54-4b14-8a66-0c276208c6f9",
  "description": "Voluptas iure beatae.",
  "livemode": false,
  "event_codes": [
    "charge_intent.payment_action_required",
    "customer.subscription.renewal.failed"
  ],
  "secret": "955e7382-62b1-49e0-94ce-65d3f19889ab",
  "status": "active",
  "url": "https://example.com/webhook",
  "created": 1781115893,
  "updated": 1781115893,
  "object": "webhook_endpoint"
}

Update webhook endpoint

Updates the URL, description, or subscribed event codes for a webhook endpoint.

Path parameters
idstringrequired

Unique identifier for the webhook endpoint.

Body parameters
urlstringoptional

HTTPS URL Frame will POST events to.

descriptionstringoptional

Optional human-readable description.

event_codesarrayoptional

Replacement list of event codes.

Returns

Returns the updated webhook endpoint.

PATCH/v1/webhook_endpoints/{id}
curl --request PATCH \
  --url https://api.framepayments.com/v1/webhook_endpoints/a70cd72f-e74a-40f2-96a2-3f60714aac4a \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "id": "74ae5278-40b8-46db-b1cd-7673a7749fbf",
  "description": "Ut quisquam ea.",
  "livemode": false,
  "event_codes": [
    "capability.ineligible",
    "transfer.requires_account_or_customer"
  ],
  "secret": "25084fdc-4112-4a6d-a02f-fbe5e59419ef",
  "status": "active",
  "url": "https://example.com/new",
  "created": 1781115893,
  "updated": 1781115893,
  "object": "webhook_endpoint"
}

Delete webhook endpoint

Soft-deletes a webhook endpoint. After deletion Frame stops delivering events to this URL.

Path parameters
idstringrequired

Unique identifier for the webhook endpoint.

Returns

Returns a deletion stub.

DELETE/v1/webhook_endpoints/{id}
curl --request DELETE \
  --url https://api.framepayments.com/v1/webhook_endpoints/a70cd72f-e74a-40f2-96a2-3f60714aac4a \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "id": "fccae3cb-7021-4ff1-89a8-6f0ebea47dbe",
  "object": "webhook_endpoint",
  "deleted": true
}

Rotate webhook signing secret

Rotates the signing secret for a webhook endpoint. The new secret is returned once in the response — store it securely. The previous secret is immediately invalidated, so configure verifiers with the new value before continuing to process events.

Path parameters
idstringrequired

Unique identifier for the webhook endpoint.

Returns

Returns the webhook endpoint with the rotated secret.

POST/v1/webhook_endpoints/{id}/rotate_secret
curl --request POST \
  --url https://api.framepayments.com/v1/webhook_endpoints/a70cd72f-e74a-40f2-96a2-3f60714aac4a/rotate_secret \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "id": "153c266c-b5e6-4c48-91c6-44cd3cc1b13b",
  "description": "Quaerat facilis nulla.",
  "livemode": false,
  "event_codes": [
    "subscription.incomplete",
    "transfer.expired"
  ],
  "secret": "tET8LsMapnk8getxcqW9RENskbELTrYB",
  "status": "active",
  "url": "https://example.com/webhook",
  "created": 1781115894,
  "updated": 1781115894,
  "object": "webhook_endpoint"
}