interface HandlesWebhooks

An optional capability for {DriverInterface} implementations whose provider can push delivery events (bounces, complaints) to Flarum via an inbound webhook.

This is intentionally a separate interface, not part of DriverInterface, so that adding bounce handling never breaks third-party drivers that do not implement it.

Methods

RequestParserInterface
getWebhookRequestParser( SettingsRepositoryInterface $settings)

The Symfony request parser for this provider. The parser is fully responsible for **authenticating** the request and normalising the payload into a {\Symfony\Component\RemoteEvent\RemoteEvent}.

string|null
getWebhookSigningSecret( SettingsRepositoryInterface $settings)

The secret passed to the parser's `parse()` call, if this provider uses one. Return null when the provider authenticates by other means (e.g.

bool
webhookConfigured( SettingsRepositoryInterface $settings)

Whether inbound webhooks can actually be received and trusted with the current settings. Drivers that require configuration the admin must supply (e.g. Mailgun's signing key) should return false until it is set, so the UI can warn that no bounces will arrive. Drivers that need no such config should simply return true. Shared provider IPs alone do not identify the account; Mailgun and Postmark require forum-specific credentials.

bool
webhooksAvailable( SettingsRepositoryInterface $settings)

Whether this driver can report bounces at all with the current settings.

bool
isPermanentFailure( MailerDeliveryEvent $event)

Whether a bounce or drop the parser reported is permanent. Flarum only flags the recipient when it is. Many providers report soft bounces as bounces too, so check the provider's own payload, available from $event->getPayload().

Details

RequestParserInterface getWebhookRequestParser( SettingsRepositoryInterface $settings)

The Symfony request parser for this provider. The parser is fully responsible for **authenticating** the request and normalising the payload into a {\Symfony\Component\RemoteEvent\RemoteEvent}.

Verification is provider-specific and lives entirely in the parser — it may check an HMAC signature (Mailgun), an account-specific IP allowlist, or an SNS certificate (SES). Callers MUST NOT attempt to verify the request themselves; they should call {\Symfony\Component\Webhook\Client\RequestParserInterface::parse()} and treat a thrown {\Symfony\Component\Webhook\Exception\RejectWebhookException} as a rejection, and a `null` return as "verified but no actionable event" (e.g. an SES/SNS subscription-confirmation handshake).

Parameters

SettingsRepositoryInterface $settings

Return Value

RequestParserInterface

string|null getWebhookSigningSecret( SettingsRepositoryInterface $settings)

The secret passed to the parser's `parse()` call, if this provider uses one. Return null when the provider authenticates by other means (e.g.

an IP allowlist) — this is a valid, fully-supported state, NOT a misconfiguration. Providers that require a secret (e.g. Mailgun) must return false from webhookConfigured() while it is missing, so the request is refused before it reaches the parser.

Parameters

SettingsRepositoryInterface $settings

Return Value

string|null

bool webhookConfigured( SettingsRepositoryInterface $settings)

Whether inbound webhooks can actually be received and trusted with the current settings. Drivers that require configuration the admin must supply (e.g. Mailgun's signing key) should return false until it is set, so the UI can warn that no bounces will arrive. Drivers that need no such config should simply return true. Shared provider IPs alone do not identify the account; Mailgun and Postmark require forum-specific credentials.

Parameters

SettingsRepositoryInterface $settings

Return Value

bool

bool webhooksAvailable( SettingsRepositoryInterface $settings)

Whether this driver can report bounces at all with the current settings.

Return false for a configuration that never delivers mail to real recipients, such as a sandbox mode, and Flarum hides bounce handling entirely instead of warning that it is not set up.

Parameters

SettingsRepositoryInterface $settings

Return Value

bool

bool isPermanentFailure( MailerDeliveryEvent $event)

Whether a bounce or drop the parser reported is permanent. Flarum only flags the recipient when it is. Many providers report soft bounces as bounces too, so check the provider's own payload, available from $event->getPayload().

Parameters

MailerDeliveryEvent $event

Return Value

bool