Webhooks

Managing webhook endpoints

Manage your webhook endpoints over the API at /api/v1/webhook_endpoints/. Every endpoint here is the same object you can manage from the Developer page at app.itspaydai.com/developer. To receive events at an endpoint, see the Webhooks overview; to verify deliveries, see Verify authenticity.

Authentication

Every request requires a Bearer JWT access token:

Code
Authorization: Bearer <JWT access token>

Requests without a valid token receive 401 UNAUTHORIZED.

Response envelope

Every response - success or error - uses the same envelope:


Code
{
  "status": true,
  "statusCode": "OK | CREATED | NO_CONTENT | BAD_REQUEST | FORBIDDEN | UNAUTHORIZED | INTERNAL_SERVER_ERROR",
  "message": "Human-readable description",
  "data": { },
  "errors": { "field": ["detail"] }
}

Passing `workspace_id`

Every endpoint is scoped to a workspace, so workspace_id is always required. Where you pass it depends on the HTTP method:

Method	Where `workspace_id` goes
`GET`, `DELETE`	Query parameter, e.g. `?workspace_id=<uuid>`
`POST`, `PATCH`	Request body field

The one exception is Reveal secret: it is a POST with no request body, so it takes workspace_id as a query parameter.

The endpoint object

Field	Type	Notes
`id`	UUID	The endpoint's identifier.
`url`	string	Destination URL. Max 2048 characters. Unique within the workspace.
`description`	string	Human-readable label. Max 255 characters.
`status`	string	One of `active`, `disabled`, `paused`.
`api_version`	string	Payload schema the endpoint is pinned to. Defaults to `2026-06-01`.
`custom_headers`	object	Extra headers sent with every delivery. See Custom headers.
`secret_hint`	string	Masked signing secret, e.g. `whsec_••••••••••••••••••5789`. The full secret is never returned here - use Reveal secret.
`consecutive_failures`	integer	Count of back-to-back failed deliveries. Resets on success.
`created_at`	datetime	ISO 8601 creation timestamp.
`updated_at`	datetime	ISO 8601 timestamp of the last change.
`enabled_events`	string[]	Event types delivered to this endpoint. See Event types.

The full signing secret (whsec_...) is only ever returned by Create (once, in the creation response) and by Reveal secret. Every other response carries secret_hint instead.

List endpoints

Returns all webhook endpoints registered for a workspace.

Code
GET /api/v1/webhook_endpoints/?workspace_id=<uuid>

Param	Type	Required	Description
`workspace_id`	UUID	Yes	Returns endpoints belonging to this workspace only.


Response 200 OK
{
  "status": true,
  "statusCode": "OK",
  "message": "...",
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "url": "https://your-server.com/webhook",
      "description": "My endpoint",
      "status": "active",
      "api_version": "2026-06-01",
      "custom_headers": {},
      "secret_hint": "whsec_••••••••••••••••••5789",
      "consecutive_failures": 0,
      "created_at": "2026-06-19T00:00:00Z",
      "updated_at": "2026-06-19T00:00:00Z",
      "enabled_events": ["sale.created", "sale.paid"]
    }
  ],
  "errors": null
}

Create endpoint

Registers a new webhook endpoint for a workspace. The signing secret is returned once in this response - save it immediately, or retrieve it later with Reveal secret.

Code
POST /api/v1/webhook_endpoints/


Request body
{
  "workspace_id": "7c448c98-390c-4994-abe8-21d0f7b899a8",
  "url": "https://your-server.com/webhook",
  "description": "My endpoint",
  "enabled_events": ["sale.created", "sale.paid"],
  "api_version": "2026-06-01"
}

Field	Type	Required	Description
`workspace_id`	UUID	Yes	Workspace to attach the endpoint to.
`url`	string	Yes	Destination URL. Max 2048 characters. Unique within the workspace.
`description`	string	No	Human-readable label. Max 255 characters.
`enabled_events`	string[]	Yes	One or more event types.
`api_version`	string	No	API version string. Defaults to `2026-06-01`.
`custom_headers`	object	No	Extra delivery headers. See Custom headers.


Response 201 Created
{
  "status": true,
  "statusCode": "CREATED",
  "message": "...",
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "url": "https://your-server.com/webhook",
    "description": "My endpoint",
    "status": "active",
    "api_version": "2026-06-01",
    "custom_headers": {},
    "consecutive_failures": 0,
    "created_at": "2026-06-19T00:00:00Z",
    "updated_at": "2026-06-19T00:00:00Z",
    "enabled_events": ["sale.created", "sale.paid"],
    "secret": "whsec_..."
  },
  "errors": null
}

Save secret immediately. It is only included in full in this creation response - afterwards, other endpoints return the masked secret_hint. You can still retrieve the full secret later via Reveal secret.

Retrieve endpoint

Fetches a single webhook endpoint by ID.

Code
GET /api/v1/webhook_endpoints/{id}/?workspace_id=<uuid>

Param	In	Type	Description
`id`	path	UUID	ID of the webhook endpoint.
`workspace_id`	query	UUID	Workspace the endpoint belongs to.

Returns the endpoint object with secret_hint (no full secret).

Update endpoint

Partially updates a webhook endpoint. Only the fields you provide are changed. Returns the updated endpoint object including secret_hint (never the full secret).

Code
PATCH /api/v1/webhook_endpoints/{id}/

Param	In	Type	Description
`id`	path	UUID	ID of the webhook endpoint.


Request body - any subset of these fields
{
  "workspace_id": "7c448c98-390c-4994-abe8-21d0f7b899a8",
  "url": "https://your-server.com/webhook-v2",
  "description": "Updated label",
  "enabled_events": ["commission.created", "commission.paid"],
  "status": "disabled",
  "custom_headers": {
    "X-Custom-Header": "value"
  }
}

Field	Type	Required	Description
`workspace_id`	UUID	Yes	Workspace the endpoint belongs to.
`url`	string	No	New destination URL. Max 2048 characters. Must be unique within the workspace.
`description`	string	No	Human-readable label. Max 255 characters.
`enabled_events`	string[]	No	Replaces the full list of subscribed events. Must contain at least one valid event type.
`status`	string	No	One of `active`, `disabled`, `paused`.
`custom_headers`	object	No	Replaces the full custom header map. See Custom headers.


Response 200 OK
{
  "status": true,
  "statusCode": "OK",
  "message": "Webhook endpoint updated successfully",
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "url": "https://your-server.com/webhook-v2",
    "description": "Updated label",
    "status": "disabled",
    "api_version": "2026-06-01",
    "custom_headers": {
      "X-Custom-Header": "value"
    },
    "secret_hint": "whsec_••••••••••••••••••5789",
    "consecutive_failures": 0,
    "created_at": "2026-06-19T00:00:00Z",
    "updated_at": "2026-06-19T12:00:00Z",
    "enabled_events": ["commission.created", "commission.paid"]
  },
  "errors": null
}


Response 400 Bad Request - validation error
{
  "status": false,
  "statusCode": "BAD_REQUEST",
  "message": "Validation failed",
  "data": null,
  "errors": {
    "custom_headers": ["The following headers are reserved and cannot be set: paydai-signature"]
  }
}

A 400 is returned for an invalid event type, a reserved custom header, a duplicate URL, or similar validation failures.

Delete endpoint

Permanently removes a webhook endpoint and all its event subscriptions.

Code
DELETE /api/v1/webhook_endpoints/{id}/?workspace_id=<uuid>

Param	In	Type	Description
`id`	path	UUID	ID of the webhook endpoint.
`workspace_id`	query	UUID	Workspace the endpoint belongs to.

Returns 204 No Content with an empty body.

Reveal secret

Returns the full signing secret for an endpoint. Use this when the secret was not saved at creation time. The secret can be retrieved again at any time by authorized workspace members.

Code
POST /api/v1/webhook_endpoints/{id}/reveal-secret/?workspace_id=<uuid>

Param	In	Type	Required	Description
`id`	path	UUID	Yes	ID of the webhook endpoint.
`workspace_id`	query	UUID	Yes	Workspace the endpoint belongs to.

Request body — none.


Response 200 OK
{
  "status": true,
  "statusCode": "OK",
  "message": "Webhook secret retrieved successfully",
  "data": {
    "secret": "whsec_da3f7794cdb79ba74d759765b44842f18dc3a41547495789"
  },
  "errors": null
}

Treat the revealed secret like a password. Store it securely and never expose it in client-side code or logs.

List supported events

Returns all valid event type strings accepted in enabled_events. See Event types for the categorized list and descriptions.

Code
GET /api/v1/webhook_endpoints/supported-events/

Returns a data array of event-type strings, e.g. ["sale.created", "sale.paid", "commission.created", ...].

Custom headers

custom_headers is a map of extra headers PayDai sends with every delivery to the endpoint - useful for routing, tenant tagging, or passing a static auth token to your receiver. Keys are header names; values are strings (max 1024 characters each). Setting custom_headers on Update replaces the entire existing map.

Reserved headers

These headers are managed by PayDai and cannot be set in custom_headers (case-insensitive). Including any of them returns 400 Bad Request:

content-type
paydai-signature
paydai-event-type
paydai-api-version
paydai-event-id
user-agent

Endpoint status values

Value	Meaning
`active`	Receiving and processing events.
`disabled`	Manually disabled.
`paused`	Paused, e.g. after repeated consecutive delivery failures.

Last modified on September 25, 2026

Overview Event types

Webhooks

Managing webhook endpoints

Authentication

Every request requires a Bearer JWT access token:

Code
Authorization: Bearer <JWT access token>

Requests without a valid token receive 401 UNAUTHORIZED.

Response envelope

Every response - success or error - uses the same envelope:


Code
{
  "status": true,
  "statusCode": "OK | CREATED | NO_CONTENT | BAD_REQUEST | FORBIDDEN | UNAUTHORIZED | INTERNAL_SERVER_ERROR",
  "message": "Human-readable description",
  "data": { },
  "errors": { "field": ["detail"] }
}

Passing `workspace_id`

Every endpoint is scoped to a workspace, so workspace_id is always required. Where you pass it depends on the HTTP method:

Method	Where `workspace_id` goes
`GET`, `DELETE`	Query parameter, e.g. `?workspace_id=<uuid>`
`POST`, `PATCH`	Request body field

The one exception is Reveal secret: it is a POST with no request body, so it takes workspace_id as a query parameter.

The endpoint object

Field	Type	Notes
`id`	UUID	The endpoint's identifier.
`url`	string	Destination URL. Max 2048 characters. Unique within the workspace.
`description`	string	Human-readable label. Max 255 characters.
`status`	string	One of `active`, `disabled`, `paused`.
`api_version`	string	Payload schema the endpoint is pinned to. Defaults to `2026-06-01`.
`custom_headers`	object	Extra headers sent with every delivery. See Custom headers.
`secret_hint`	string	Masked signing secret, e.g. `whsec_••••••••••••••••••5789`. The full secret is never returned here - use Reveal secret.
`consecutive_failures`	integer	Count of back-to-back failed deliveries. Resets on success.
`created_at`	datetime	ISO 8601 creation timestamp.
`updated_at`	datetime	ISO 8601 timestamp of the last change.
`enabled_events`	string[]	Event types delivered to this endpoint. See Event types.

The full signing secret (whsec_...) is only ever returned by Create (once, in the creation response) and by Reveal secret. Every other response carries secret_hint instead.

List endpoints

Returns all webhook endpoints registered for a workspace.

Code
GET /api/v1/webhook_endpoints/?workspace_id=<uuid>

Param	Type	Required	Description
`workspace_id`	UUID	Yes	Returns endpoints belonging to this workspace only.


Response 200 OK
{
  "status": true,
  "statusCode": "OK",
  "message": "...",
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "url": "https://your-server.com/webhook",
      "description": "My endpoint",
      "status": "active",
      "api_version": "2026-06-01",
      "custom_headers": {},
      "secret_hint": "whsec_••••••••••••••••••5789",
      "consecutive_failures": 0,
      "created_at": "2026-06-19T00:00:00Z",
      "updated_at": "2026-06-19T00:00:00Z",
      "enabled_events": ["sale.created", "sale.paid"]
    }
  ],
  "errors": null
}

Create endpoint

Registers a new webhook endpoint for a workspace. The signing secret is returned once in this response - save it immediately, or retrieve it later with Reveal secret.

Code
POST /api/v1/webhook_endpoints/


Request body
{
  "workspace_id": "7c448c98-390c-4994-abe8-21d0f7b899a8",
  "url": "https://your-server.com/webhook",
  "description": "My endpoint",
  "enabled_events": ["sale.created", "sale.paid"],
  "api_version": "2026-06-01"
}

Field	Type	Required	Description
`workspace_id`	UUID	Yes	Workspace to attach the endpoint to.
`url`	string	Yes	Destination URL. Max 2048 characters. Unique within the workspace.
`description`	string	No	Human-readable label. Max 255 characters.
`enabled_events`	string[]	Yes	One or more event types.
`api_version`	string	No	API version string. Defaults to `2026-06-01`.
`custom_headers`	object	No	Extra delivery headers. See Custom headers.


Response 201 Created
{
  "status": true,
  "statusCode": "CREATED",
  "message": "...",
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "url": "https://your-server.com/webhook",
    "description": "My endpoint",
    "status": "active",
    "api_version": "2026-06-01",
    "custom_headers": {},
    "consecutive_failures": 0,
    "created_at": "2026-06-19T00:00:00Z",
    "updated_at": "2026-06-19T00:00:00Z",
    "enabled_events": ["sale.created", "sale.paid"],
    "secret": "whsec_..."
  },
  "errors": null
}

Retrieve endpoint

Fetches a single webhook endpoint by ID.

Code
GET /api/v1/webhook_endpoints/{id}/?workspace_id=<uuid>

Param	In	Type	Description
`id`	path	UUID	ID of the webhook endpoint.
`workspace_id`	query	UUID	Workspace the endpoint belongs to.

Returns the endpoint object with secret_hint (no full secret).

Update endpoint

Partially updates a webhook endpoint. Only the fields you provide are changed. Returns the updated endpoint object including secret_hint (never the full secret).

Code
PATCH /api/v1/webhook_endpoints/{id}/

Param	In	Type	Description
`id`	path	UUID	ID of the webhook endpoint.


Request body - any subset of these fields
{
  "workspace_id": "7c448c98-390c-4994-abe8-21d0f7b899a8",
  "url": "https://your-server.com/webhook-v2",
  "description": "Updated label",
  "enabled_events": ["commission.created", "commission.paid"],
  "status": "disabled",
  "custom_headers": {
    "X-Custom-Header": "value"
  }
}

Field	Type	Required	Description
`workspace_id`	UUID	Yes	Workspace the endpoint belongs to.
`url`	string	No	New destination URL. Max 2048 characters. Must be unique within the workspace.
`description`	string	No	Human-readable label. Max 255 characters.
`enabled_events`	string[]	No	Replaces the full list of subscribed events. Must contain at least one valid event type.
`status`	string	No	One of `active`, `disabled`, `paused`.
`custom_headers`	object	No	Replaces the full custom header map. See Custom headers.


Response 200 OK
{
  "status": true,
  "statusCode": "OK",
  "message": "Webhook endpoint updated successfully",
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "url": "https://your-server.com/webhook-v2",
    "description": "Updated label",
    "status": "disabled",
    "api_version": "2026-06-01",
    "custom_headers": {
      "X-Custom-Header": "value"
    },
    "secret_hint": "whsec_••••••••••••••••••5789",
    "consecutive_failures": 0,
    "created_at": "2026-06-19T00:00:00Z",
    "updated_at": "2026-06-19T12:00:00Z",
    "enabled_events": ["commission.created", "commission.paid"]
  },
  "errors": null
}


Response 400 Bad Request - validation error
{
  "status": false,
  "statusCode": "BAD_REQUEST",
  "message": "Validation failed",
  "data": null,
  "errors": {
    "custom_headers": ["The following headers are reserved and cannot be set: paydai-signature"]
  }
}

A 400 is returned for an invalid event type, a reserved custom header, a duplicate URL, or similar validation failures.

Delete endpoint

Permanently removes a webhook endpoint and all its event subscriptions.

Code
DELETE /api/v1/webhook_endpoints/{id}/?workspace_id=<uuid>

Param	In	Type	Description
`id`	path	UUID	ID of the webhook endpoint.
`workspace_id`	query	UUID	Workspace the endpoint belongs to.

Returns 204 No Content with an empty body.

Reveal secret

Returns the full signing secret for an endpoint. Use this when the secret was not saved at creation time. The secret can be retrieved again at any time by authorized workspace members.

Code
POST /api/v1/webhook_endpoints/{id}/reveal-secret/?workspace_id=<uuid>

Param	In	Type	Required	Description
`id`	path	UUID	Yes	ID of the webhook endpoint.
`workspace_id`	query	UUID	Yes	Workspace the endpoint belongs to.

Request body — none.


Response 200 OK
{
  "status": true,
  "statusCode": "OK",
  "message": "Webhook secret retrieved successfully",
  "data": {
    "secret": "whsec_da3f7794cdb79ba74d759765b44842f18dc3a41547495789"
  },
  "errors": null
}

Treat the revealed secret like a password. Store it securely and never expose it in client-side code or logs.

List supported events

Returns all valid event type strings accepted in enabled_events. See Event types for the categorized list and descriptions.

Code
GET /api/v1/webhook_endpoints/supported-events/

Returns a data array of event-type strings, e.g. ["sale.created", "sale.paid", "commission.created", ...].

Custom headers

Reserved headers

These headers are managed by PayDai and cannot be set in custom_headers (case-insensitive). Including any of them returns 400 Bad Request:

content-type
paydai-signature
paydai-event-type
paydai-api-version
paydai-event-id
user-agent

Endpoint status values

Value	Meaning
`active`	Receiving and processing events.
`disabled`	Manually disabled.
`paused`	Paused, e.g. after repeated consecutive delivery failures.

Last modified on September 25, 2026

Overview Event types

Authentication

Response envelope

Passing workspace_id

The endpoint object

List endpoints

Create endpoint

Retrieve endpoint

Update endpoint

Delete endpoint

Reveal secret

List supported events

Custom headers

Reserved headers

Endpoint status values

Authentication

Response envelope

Passing workspace_id

The endpoint object

List endpoints

Create endpoint

Retrieve endpoint

Update endpoint

Delete endpoint

Reveal secret

List supported events

Custom headers

Reserved headers

Endpoint status values

Passing `workspace_id`

Passing `workspace_id`