Webhook

A Webhook in the Paylias network enables real-time event notifications to applications. When specific events occur, webhooks deliver event data to configured endpoints, allowing applications to react immediately rather than polling for updates.

Overview

Each Webhook:

Links to a specific Domain
Subscribes to specific event types
Delivers events in real-time
Supports signature verification
Handles automatic retries

Multiple webhook subscriptions cannot subscribe to the same event.

Event Types

Event Type	Description
`payments.created`	Triggered when a new payment is created
`payment_admission.created`	Triggered when a new payment admission is created
`payment_admission.updated`	Triggered when a payment admission is updated
`payment_submission.created`	Triggered when a new payment submission is created
`payment_submission.updated`	Triggered when a payment submission is updated
`payment_admission_task.created`	Triggered when a new admission task is created
`payment_admission_task.updated`	Triggered when an admission task is updated
`payment_submission_task.created`	Triggered when a new submission task is created
`payment_submission_task.updated`	Triggered when a submission task is updated

API Resource

Property	Type	Description	Notes
`token`	string	Unique identifier for the webhook	Auto-generated upon creation
`partner_id`	string	Associated Domain ID	Links to Domain record
`name`	string	Display name for the webhook	Required
`description`	string	Purpose or usage notes	Optional
`endpoint`	string	URL to receive events	Required
`secret`	string	Signing secret for verification	Optional
`events`	array	Subscribed event types	Required
`enabled`	boolean	Active status of webhook	Can be toggled
`created_at`	timestamp	Creation timestamp	Unix timestamp in seconds
`updated_at`	timestamp	Last update timestamp	Unix timestamp in seconds

Delivery Status Types

Status	Value	Description
`Undelivered`	0	Event pending delivery
`Delivered`	1	Event successfully delivered

Authentication

All Webhook operations require:

JWT token in the Authorization header
Domain token in the X-Partner-ID header

Security

When a webhook secret is configured:

All event payloads are signed
Signature included in X-Sfpy-Signature header
Allows verification of Paylias as the sender

API Endpoints

Create Webhook

Creates a new webhook subscription for specific events.

Required Parameters

Parameter	Type	Required	Description
`name`	string	Yes	Display name for webhook
`description`	string	No	Usage description
`endpoint`	string	Yes	URL to receive events
`secret`	string	No	Signing secret for verification
`events`	string[]	Yes	Array of event types to subscribe to
`enabled`	boolean	Yes	Initial active status

`POST /api/v1/csp/webhook`

curl --location 'https://production.oysterapi.net/csp/api/v1/csp/webhook' \
--header 'X-Partner-ID: part_cjes76vsemvj3obsnc30' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <jwt_token>' \
--data '{
    "name": "Link Events",
    "description": "Webhook to consume link events",
    "endpoint": "https://api.stripe.com/webhook/link-events",
    "secret": "2ff46f215a5bb7da8f7fda9b2b0c9ef86c9e7de6",
    "events": [
        "payments.created"
    ],
    "enabled": false
}'

Example Response

{
    "ok": true,
    "data": {
        "token": "whk_cjf0qivsemvkg2on8f9g",
        "partner_id": "part_cjes76vsemvj3obsnc30",
        "name": "Link Events",
        "description": "Webhook to consume link events",
        "endpoint": "https://api.stripe.com/webhook/link-events",
        "secret": "2ff46f215a5bb7da8f7fda9b2b0c9ef86c9e7de6",
        "events": [
            {
                "token": "evt_cjf0qivsemvkg2on8fa0",
                "webhook_id": "whk_cjf0qivsemvkg2on8f9g",
                "type": "payments.created",
                "created_at": {
                    "seconds": 1692273996
                },
                "updated_at": {
                    "seconds": 1692273996
                }
            }
        ],
        "created_at": {
            "seconds": 1692273996
        },
        "updated_at": {
            "seconds": 1692273996
        }
    }
}

Update Webhook

Updates an existing webhook subscription.

Path Parameters

Parameter	Type	Required	Description
`webhookId`	string	Yes	Webhook to update

Required Parameters

Parameter	Type	Required	Description
`name`	string	Yes	Updated display name
`description`	string	No	Updated description
`endpoint`	string	Yes	Updated URL
`secret`	string	No	Updated signing secret
`add_events`	string[]	No	Events to subscribe to
`remove_events`	string[]	No	Events to unsubscribe from
`enabled`	boolean	Yes	Updated active status

`PUT /api/v1/csp/webhook/{webhookId}`

curl --location --request PUT 'https://production.oysterapi.net/csp/api/v1/csp/webhook/whk_cjf0qivsemvkg2on8f9g' \
--header 'X-Partner-ID: part_cjes76vsemvj3obsnc30' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <jwt_token>' \
--data '{
    "name": "Link Events",
    "description": "Webhook to consume link events",
    "endpoint": "https://api.stripe.com/webhook/link-events",
    "secret": "2ff46f215a5bb7da8f7fda9b2b0c9ef86c9e7de6",
    "add_events": [
        "payments.updated"
    ],
    "remove_events": [],
    "enabled": true
}'

Example Response

{
    "ok": true,
    "data": {
        "token": "whk_cjf0qivsemvkg2on8f9g",
        "partner_id": "part_cjes76vsemvj3obsnc30",
        "name": "Link Events",
        "description": "Webhook to consume link events",
        "enabled": true,
        "endpoint": "https://api.stripe.com/webhook/link-events",
        "secret": "2ff46f215a5bb7da8f7fda9b2b0c9ef86c9e7de6",
        "events": [
            {
                "token": "evt_cjf0qivsemvkg2on8fa0",
                "webhook_id": "whk_cjf0qivsemvkg2on8f9g",
                "type": "payments.created",
                "created_at": {
                    "seconds": 1692273996
                },
                "updated_at": {
                    "seconds": 1692273996
                }
            },
            {
                "token": "evt_cjf186vsemvkg2on8fag",
                "webhook_id": "whk_cjf0qivsemvkg2on8f9g",
                "type": "payments.updated",
                "created_at": {
                    "seconds": 1692275740
                },
                "updated_at": {
                    "seconds": 1692275740
                }
            }
        ],
        "created_at": {
            "seconds": 1692273996
        },
        "updated_at": {
            "seconds": 1692275740
        }
    }
}

Find Webhook

Retrieves details of a specific webhook.

Path Parameters

Parameter	Type	Required	Description
`webhookId`	string	Yes	Webhook to retrieve

`GET /api/v1/csp/webhook/{webhookId}`

curl --location 'https://production.oysterapi.net/csp/api/v1/csp/webhook/whk_cjf0qivsemvkg2on8f9g' \
--header 'X-Partner-ID: part_cjes76vsemvj3obsnc30' \
--header 'Authorization: Bearer <jwt_token>'

Example Response

{
    "ok": true,
    "data": {
        "token": "whk_cjf0qivsemvkg2on8f9g",
        "partner_id": "part_cjes76vsemvj3obsnc30",
        "name": "Link Events",
        "description": "Webhook to consume link events",
        "enabled": true,
        "endpoint": "https://api.stripe.com/webhook/link-events",
        "secret": "2ff46f215a5bb7da8f7fda9b2b0c9ef86c9e7de6",
        "events": [
            {
                "token": "evt_cjf0qivsemvkg2on8fa0",
                "webhook_id": "whk_cjf0qivsemvkg2on8f9g",
                "type": "payments.created",
                "created_at": {
                    "seconds": 1692273996
                },
                "updated_at": {
                    "seconds": 1692273996
                }
            },
            {
                "token": "evt_cjf186vsemvkg2on8fag",
                "webhook_id": "whk_cjf0qivsemvkg2on8f9g",
                "type": "payments.updated",
                "created_at": {
                    "seconds": 1692275740
                },
                "updated_at": {
                    "seconds": 1692275740
                }
            }
        ],
        "created_at": {
            "seconds": 1692273996
        },
        "updated_at": {
            "seconds": 1692279738
        }
    }
}

List Webhooks

Retrieves a paginated list of webhooks with optional filters.

Query Parameters

Parameter	Type	Required	Description
`tokens`	string[]	No	Filter by webhook tokens
`endpoints`	string[]	No	Filter by endpoints
`names`	string[]	No	Filter by names
`enabled`	boolean	Yes	Filter by status
`limit`	integer	Yes	Results per page
`page`	integer	Yes	Page number

`GET /api/v1/csp/webhook`

curl --location 'https://production.oysterapi.net/csp/api/v1/csp/webhook?tokens=whk_cjf0qavsemvkg2on8f8g&endpoints=https%3A%2F%2Fapi.stripe.com%2Fwebhook%2Flink-events&names=Events&enabled=true&page=1' \
--header 'X-Partner-ID: part_cjes76vsemvj3obsnc30' \
--header 'Authorization: Bearer <jwt_token>'

Example Response

{
    "ok": true,
    "data": {
        "count": 1,
        "webhooks": [
            {
                "token": "whk_cjf0qavsemvkg2on8f8g",
                "partner_id": "part_cjes76vsemvj3obsnc30",
                "name": "Link Events",
                "description": "Webhook to consume link events",
                "endpoint": "https://api.stripe.com/webhook/link-events",
                "secret": "2ff46f215a5bb7da8f7fda9b2b0c9ef86c9e7de6",
                "created_at": {
                    "seconds": 1692273963
                },
                "updated_at": {
                    "seconds": 1692273964
                }
            }
        ]
    }
}

Delete Webhook

Removes a webhook subscription.

Path Parameters

Parameter	Type	Required	Description
`webhookId`	string	Yes	Webhook to delete

`DELETE /api/v1/csp/webhook/{webhookId}`

curl --location --request DELETE 'https://production.oysterapi.net/csp/api/v1/csp/webhook/whk_f45cc34f-aa98-4512-b272-18bb22177e0c' \
--header 'X-Partner-ID: part_cjes76vsemvj3obsnc30' \
--header 'Authorization: Bearer <jwt_token>'

Example Response

{
    "ok": true
}

Common Error Codes

Error Code	Description
`error.bad_request`	Invalid or missing required parameters
`error.resource_conflict`	Event already subscribed by another webhook
`error.resource_not_found`	Webhook not found
`error.unauthorized_access`	Invalid or missing authentication
`500`, `502`, `503`, `504`	Server-side errors