Webhooks (API Resource)

Manage webhook endpoints programmatically via the API.

TIP

For handling incoming webhook events, see the Webhook Handling guide.

Create a Webhook Endpoint

use LegionHQ\LaravelPayrex\Facades\Payrex;

$webhook = Payrex::webhooks()->create([
    'url' => 'https://example.com/webhooks/shipments',         // Required. HTTPS URL
    'events' => ['payment_intent.succeeded'],                     // Required
    'description' => 'This is the webhook used for sending shipments after receiving successfully paid payments',
]);

// Store the secret_key for signature verification
$secret = $webhook->secretKey;

Returns a Webhook Endpoint resource.

Webhook Secret

The secret_key returned here is the signing secret for this webhook endpoint. If this is the endpoint your application uses to receive webhooks, set it as your PAYREX_WEBHOOK_SECRET environment variable so the package can verify incoming signatures. You can also find this value in the PayRex Dashboard under each webhook endpoint's details.

Example Response:

{
    "id": "wh_xxxxx",
    "resource": "webhook",
    "secret_key": "whsk_xxxxx",
    "status": "enabled",
    "description": "This is the webhook used for sending shipments after receiving successfully paid payments",
    "livemode": false,
    "url": "https://example.com/webhooks/shipments",
    "events": [
        "payment_intent.succeeded"
    ],
    "created_at": 1706056262,
    "updated_at": 1706056471
}

List Webhook Endpoints

Basic

$webhooks = Payrex::webhooks()->list(['limit' => 10]);

foreach ($webhooks->data as $webhook) {
    echo "{$webhook->url} — {$webhook->status}";
}

With Filters

// Search by URL
$webhooks = Payrex::webhooks()->list([
    'url' => 'https://example.com',
]);

// Search by description
$webhooks = Payrex::webhooks()->list([
    'description' => 'shipments',
]);

Returns a list of Webhook Endpoint resources.

List Parameters

Parameter	Type	Required	Description
limit	int	No	Number of results (min: 1, max: 100)
before	string	No	Cursor for backward pagination (resource ID)
after	string	No	Cursor for forward pagination (resource ID)
url	string	No	Search webhooks by URL
description	string	No	Search webhooks by description

Pagination

// In a controller — returns a CursorPaginator for UI pagination
$webhooks = Payrex::webhooks()->paginate(perPage: 10);

See Pagination for more details on cursor-based pagination.

Example Response:

{
    "resource": "list",
    "data": [
        {
            "id": "wh_xxxxx",
            "resource": "webhook",
            "secret_key": "whsk_xxxxx",
            "status": "enabled",
            "description": "This is the webhook used for sending shipments after receiving successfully paid payments",
            "livemode": false,
            "url": "https://example.com/webhooks/shipments",
            "events": ["payment_intent.succeeded"],
            "created_at": 1706056262,
            "updated_at": 1706056471
        },
        {
            "id": "wh_yyyyy",
            "resource": "webhook",
            "secret_key": "whsk_yyyyy",
            "status": "disabled",
            "description": "Staging webhook endpoint",
            "livemode": false,
            "url": "https://staging.example.com/webhooks",
            "events": ["billing_statement.created", "billing_statement.paid"],
            "created_at": 1706056300,
            "updated_at": 1706056400
        }
    ],
    "has_more": false
}

Retrieve a Webhook Endpoint

$webhook = Payrex::webhooks()->retrieve('wh_xxxxx');

echo $webhook->url;        // 'https://example.com/webhooks/shipments'
echo $webhook->status;     // WebhookEndpointStatus::Enabled
echo $webhook->secretKey;  // 'whsk_xxxxx'
$webhook->events;          // ['payment_intent.succeeded']

Returns a Webhook Endpoint resource.

Update a Webhook Endpoint

$webhook = Payrex::webhooks()->update('wh_xxxxx', [
    'url' => 'https://example.com/webhooks/updated',
    'events' => ['payment_intent.succeeded', 'refund.created'],
    'description' => 'Production order fulfillment webhook',
]);

Returns a Webhook Endpoint resource.

Example Response:

{
    "id": "wh_xxxxx",
    "resource": "webhook",
    "secret_key": "whsk_xxxxx",
    "status": "enabled",
    "description": "Production order fulfillment webhook",
    "livemode": false,
    "url": "https://example.com/webhooks/updated",
    "events": [
        "payment_intent.succeeded",
        "refund.created"
    ],
    "created_at": 1706056262,
    "updated_at": 1706056600
}

Delete a Webhook Endpoint

Payrex::webhooks()->delete('wh_xxxxx');

Returns a Deleted Resource.

Example Response:

{
    "id": "wh_xxxxx",
    "resource": "webhook",
    "deleted": true
}

Enable a Webhook Endpoint

use LegionHQ\LaravelPayrex\Enums\WebhookEndpointStatus;

$webhook = Payrex::webhooks()->enable('wh_xxxxx');

echo $webhook->status; // WebhookEndpointStatus::Enabled

Returns a Webhook Endpoint resource.

Disable a Webhook Endpoint

use LegionHQ\LaravelPayrex\Enums\WebhookEndpointStatus;

$webhook = Payrex::webhooks()->disable('wh_xxxxx');

echo $webhook->status; // WebhookEndpointStatus::Disabled

Returns a Webhook Endpoint resource.

Example Response:

{
    "id": "wh_xxxxx",
    "resource": "webhook",
    "secret_key": "whsk_xxxxx",
    "status": "disabled",
    "description": "This is the webhook used for sending shipments after receiving successfully paid payments",
    "livemode": false,
    "url": "https://example.com/webhooks/shipments",
    "events": [
        "payment_intent.succeeded"
    ],
    "created_at": 1706056262,
    "updated_at": 1706056500
}

Webhook Endpoint Resource

Field	Type	Description
id	string	Unique identifier (wh_ prefix)
resource	string	Always webhook. Note: the PayRex API returns "webhook" as the resource type, while the package uses WebhookEndpoint as the DTO class name to avoid confusion with webhook events.
secret_key	string	Secret for webhook signature verification (whsk_ prefix)
url	string	HTTPS endpoint receiving events
events	array	Event types the webhook monitors
description	string|null	Reference text
status	string	See WebhookEndpointStatus
livemode	boolean	Live or test mode
created_at	integer	Unix timestamp
updated_at	integer	Unix timestamp

Property Access

Response field names above are shown in snake_case (matching the raw API response). In PHP, access them as camelCase typed properties on the DTO — e.g., secret_key becomes $webhook->secretKey. See Response Data for details.

Further Reading

• Webhook Handling — Set up event listeners for incoming webhooks
• Artisan Commands — Manage webhook endpoints via CLI
• Configuration — Webhook Settings — Webhook path, secret, and tolerance