Webhook

Дата обновления перевода 2025-09-21

Webhook

Компонент Webhook используется для ответа на удаленные веб-хуки для запуска действий в вашем приложении. Этот документ посвящен использованию веб-хуков для прослушивания удаленных событий в других компонентах Symfony.

Установка

1
$ composer require symfony/webhook

Использование в сочетании с компонентом Mailer

Screencast

Предпочитаете видео-туториалы? Просмотрите Скринкаст про компонент Webhook для событий Email.

При использовании стороннего поставщика почтовых услуг можно использовать компонент Webhook для для получения вызовов веб-хуков от этого поставщика.

В настоящее время следующие сторонние поставщики почтовых услуг поддерживают веб-хуки:

7.1

Поддержка для Resend и MailerSend была представлена в Symfony 7.1.

7.2

Интеграции Mandrill, Mailomat, Mailtrap, и Sweego были представлены в Symfony 7.2.

7.3

Интеграция AhaSend была представлена в Symfony 7.3.

Note

Установите сторонний поставщик почтовых услуг, который вы хотите использовать, как описано
документации компонента Mailer . В качестве примера в этом документе используется поставщик Mailgun.

Чтобы подключить поставщика к вашему приложению, необходимо сконфигурировать маршрутизацию компонента Webhook:

1
2
3
4
5
6
7
# config/packages/framework.yaml
framework:
    webhook:
        routing:
            mailer_mailgun:
                service: 'mailer.webhook.request_parser.mailgun'
                secret: '%env(MAILER_MAILGUN_SECRET)%'

В этом примере мы используем mailer_mailgun в качестве имени маршрутизации веб-хука. Имя маршрутизации должно быть уникальным, поскольку именно оно связывает поставщика с вашим кодом потребителя веб-хука.

Имя маршрутизации веб-хука является частью URL-адреса, который необходимо сконфигурировать в стороннем поставщике почтовых услуг. URL-адрес представляет собой конкатенацию вашего доменного имени и имени маршрутизации, которое вы выбрали в конфигурации (например, https://example.com/webhook/mailer_mailgun.

Для Mailgun вы получите секрет для веб-хука. Сохраните этот секрет как MAILER_MAILGUN_SECRET (в :doc:cc18ac90757fec909d1a952bc8d83d503ea4e68b.env``).

После этого добавьте потребителя RemoteEvent,
чтобы реагировать на входящие веб-хуки (имя маршрутизации веб-хука - это то, что связывает ваш класс с поставщиком).

Для веб-хуков почтового сервера реагируйте на события MailerDeliveryEvent или MailerEngagementEvent:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
use Symfony\Component\RemoteEvent\Attribute\AsRemoteEventConsumer;
use Symfony\Component\RemoteEvent\Consumer\ConsumerInterface;
use Symfony\Component\RemoteEvent\Event\Mailer\MailerDeliveryEvent;
use Symfony\Component\RemoteEvent\Event\Mailer\MailerEngagementEvent;
use Symfony\Component\RemoteEvent\RemoteEvent;

#[AsRemoteEventConsumer('mailer_mailgun')]
class WebhookListener implements ConsumerInterface
{
    public function consume(RemoteEvent $event): void
    {
        if ($event instanceof MailerDeliveryEvent) {
            $this->handleMailDelivery($event);
        } elseif ($event instanceof MailerEngagementEvent) {
            $this->handleMailEngagement($event);
        } else {
            // Это не событие электронной почты
            return;
        }
    }

    private function handleMailDelivery(MailerDeliveryEvent $event): void
    {
        // Обработать событие доставки почты
    }

    private function handleMailEngagement(MailerEngagementEvent $event): void
    {
        // Обработать событие привлечения почты
    }
}

Использование в сочетании с компонентом Notifier

Использование компонента Webhook при использовании стороннего транспорта в Notifier очень похоже на использование в Mailer.

В настоящее время следующие сторонние SMS-транспорты поддерживают веб-хуки:

SMS-?????? ??? ??????? ???????
Twilio notifier.webhook.request_parser.twilio
Smsbox notifier.webhook.request_parser.smsbox
Sweego notifier.webhook.request_parser.sweego
Vonage notifier.webhook.request_parser.vonage

Для SMS веб-хуков реагируйте на событие SmsEvent:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
use Symfony\Component\RemoteEvent\Attribute\AsRemoteEventConsumer;
use Symfony\Component\RemoteEvent\Consumer\ConsumerInterface;
use Symfony\Component\RemoteEvent\Event\Sms\SmsEvent;
use Symfony\Component\RemoteEvent\RemoteEvent;

#[AsRemoteEventConsumer('notifier_twilio')]
class WebhookListener implements ConsumerInterface
{
    public function consume(RemoteEvent $event): void
    {
        if ($event instanceof SmsEvent) {
            $this->handleSmsEvent($event);
        } else {
            // Это не является событием SMS
            return;
        }
    }

    private function handleSmsEvent(SmsEvent $event): void
    {
        // Обработать событие SMS
    }
}

Создание пользовательского Webhook

Tip

Начиная с MakerBundle v1.58.0, вы можете запустить php bin/console make:webhook,
чтобы сгенерировать анализатор запросов и файлов потребителей, необходимые для создания
вашего собственного Webhook.