telvero-sales-backoffice/vendor/mollie/mollie-api-php/docs/recipes/webhooks/manage-webhooks.md

Manage Webhooks

How to retrieve, update, delete, test, and list webhooks using the Mollie API.

Get a Webhook

use Mollie\Api\Http\Requests\GetWebhookRequest;

try {
    // Get a specific webhook using direct request
    $webhook = $mollie->send(
        new GetWebhookRequest(
            id: 'wh_4KgGJJSZpH'
        )
    );

    echo "Webhook {$webhook->id}:\n";
    echo "- URL: {$webhook->url}\n";
    echo "- Name: {$webhook->name}\n";
    echo "- Event Types: {$webhook->eventTypes}\n";
    echo "- Status: {$webhook->status}\n";
} catch (\Mollie\Api\Exceptions\ApiException $e) {
    echo "API call failed: " . htmlspecialchars($e->getMessage());
}

Update a Webhook

use Mollie\Api\Http\Requests\UpdateWebhookRequest;
use Mollie\Api\Webhooks\WebhookEventType;

try {
    // Update webhook properties
    $webhook = $mollie->send(
        new UpdateWebhookRequest(
            id: 'wh_4KgGJJSZpH',
            url: 'https://updated-example.com/webhook',
            name: 'Updated webhook name',
            eventTypes: WebhookEventType::PAYMENT_LINK_PAID
        )
    );

    echo "Webhook updated successfully\n";
    echo "New URL: {$webhook->url}\n";
} catch (\Mollie\Api\Exceptions\ApiException $e) {
    echo "API call failed: " . htmlspecialchars($e->getMessage());
}

Delete a Webhook

use Mollie\Api\Http\Requests\DeleteWebhookRequest;

try {
    // Delete a webhook
    $mollie->send(
        new DeleteWebhookRequest(
            id: 'wh_4KgGJJSZpH'
        )
    );

    echo "Webhook deleted successfully\n";
} catch (\Mollie\Api\Exceptions\ApiException $e) {
    echo "API call failed: " . htmlspecialchars($e->getMessage());
}

Test a Webhook

use Mollie\Api\Http\Requests\TestWebhookRequest;

try {
    // Test webhook delivery
    $result = $mollie->send(
        new TestWebhookRequest(
            id: 'wh_4KgGJJSZpH'
        )
    );

    echo "Webhook test initiated\n";
    echo "Test status: Success\n";
} catch (\Mollie\Api\Exceptions\ApiException $e) {
    echo "Webhook test failed: " . htmlspecialchars($e->getMessage());
}

List All Webhooks

use Mollie\Api\Http\Requests\GetPaginatedWebhooksRequest;

try {
    // List all webhooks with pagination
    $webhooks = $mollie->send(
        new GetPaginatedWebhooksRequest()
    );

    foreach ($webhooks as $webhook) {
        echo "Webhook {$webhook->id}:\n";
        echo "- URL: {$webhook->url}\n";
        echo "- Name: {$webhook->name}\n";
        echo "- Event Types: {$webhook->eventTypes}\n";
        echo "- Status: {$webhook->status}\n";
        echo "- Created: {$webhook->createdAt}\n\n";
    }

    // Handle pagination if needed
    if ($webhooks->hasNext()) {
        $nextPage = $webhooks->next();
        // Process next page...
    }
} catch (\Mollie\Api\Exceptions\ApiException $e) {
    echo "API call failed: " . htmlspecialchars($e->getMessage());
}

Using Endpoint Collections (Legacy Style)

try {
    // Get a webhook
    $webhook = $mollie->webhooks->get('wh_4KgGJJSZpH');

    // Update a webhook
    $webhook = $mollie->webhooks->update('wh_4KgGJJSZpH', [
        'url' => 'https://updated-example.com/webhook',
        'name' => 'Updated name'
    ]);

    // Delete a webhook
    $mollie->webhooks->delete('wh_4KgGJJSZpH');

    // Test a webhook
    $mollie->webhooks->test('wh_4KgGJJSZpH');

    // List webhooks
    $webhooks = $mollie->webhooks->page();

    // Use convenience methods on webhook resource
    $webhook = $mollie->webhooks->get('wh_4KgGJJSZpH');

    // Update using convenience method
    $webhook->update([
        'name' => 'New name'
    ]);

    // Delete using convenience method
    $webhook->delete();

    // Test using convenience method
    $webhook->test();
} catch (\Mollie\Api\Exceptions\ApiException $e) {
    echo "API call failed: " . htmlspecialchars($e->getMessage());
}

The Response

$webhook->resource;    // "webhook"
$webhook->id;          // "wh_4KgGJJSZpH"
$webhook->url;         // "https://example.com/webhook"
$webhook->profileId;   // "pfl_v9hTwCvYqw"
$webhook->createdAt;   // "2023-12-25T10:30:54+00:00"
$webhook->name;        // "Payment notifications"
$webhook->eventTypes;  // "payment-link.paid"
$webhook->status;      // "enabled"
$webhook->_links;      // Object containing webhook links

Additional Notes

• Webhook Updates:

  • All parameters are optional when updating
  • Only specify fields you want to change

• Webhook Testing:

  • Tests webhook delivery by sending a test payload
  • Useful for verifying webhook URL accessibility
  • Check your webhook endpoint logs to confirm receipt
  • Test payloads may differ from actual event payloads

• Webhook Deletion:

  • Permanently removes the webhook
  • Cannot be undone
  • Stop receiving notifications for deleted webhooks immediately

• Listing Webhooks:

  • Returns all webhooks in your account
  • Results are paginated
  • Use hasNext() and next() for pagination

• Convenience Methods:

  • Webhook resources include convenience methods (update(), delete(), test())
  • These methods operate on the current webhook instance
  • Simplify common operations without needing to specify the webhook ID again

• Error Handling:

  • Webhook operations may fail due to network issues
  • Handle ApiException to catch and respond to errors appropriately
  • Common errors include webhook not found (404) or validation errors (422)