Webhook Delivery Alerts¶

Webhook delivery alerts notify your team when a retryable delivery failure reaches the configured attempt limit. A declined payment does not trigger an alert merely because the payment failed: alerts concern delivery to your receiving endpoint.

Configure the recipient¶

1. Open Business Settings → Developers → Webhooks in Portal.
2. Enter one plain email address, up to 254 characters, in Webhook alert recipient and select Save recipient. Choose a mailbox monitored by the team responsible for your receiving endpoint.
3. Reopen the configuration and confirm the saved address.

The recipient applies to the selected merchant account. The form is available to merchant administrators and for a selected member of a merchant group; cashiers do not see it. Leading and trailing whitespace is removed. Leaving the setting empty and saving removes the recipient and displays Alerts not configured. Alerts do not fall back to the merchant's business email or the payer's email address.

Saving a recipient does not enable the API alert service or send a verification email. When that service is enabled, its background job can send pending alerts to the configured recipient. The recipient configuration UI displays Recipient configured. Delivery alerts require the API alert service to be enabled. when an address is saved.

Understand the alert schedule¶

Alerts are grouped by webhook subscription rather than sending a separate email for every exhausted delivery. The notification sequence starts with the first retryable delivery failure that exhausts its attempts. Newly exhausted deliveries for the same subscription are grouped into the sequence, with at most five scheduled notices:

Groups with no newly exhausted deliveries do not send an email. These intervals describe the alert schedule. The background job checks each minute, and job processing or mail delivery can delay a notice; the times are approximate and do not define the webhook delivery retry schedule.

A failed mail submission is retried independently of the notification schedule. Retrying an email does not repeat the payment or the webhook delivery. Duplicate emails are possible, for example if the mail server accepts a message and the worker stops before recording that acceptance.

Recovery and pending alerts¶

BPAYD manages the restart policy for alert sequences. After the final notice, each additional failure does not automatically start another sequence. The supported policies are:

• Restart after recovery: only a successful webhook delivery after the fifth alert window re-arms alerting. The next delivery that exhausts its attempts starts a new sequence. Successes during earlier windows do not restart the sequence or discard pending groups. Pending alerts from earlier incidents are retained.
• Keep the sequence closed: recovery does not automatically restart a completed sequence.

Confirm the applicable policy with BPAYD. Changing the recipient does not select a restart policy.

Without a configured recipient, pending alerts are retained. Adding a recipient later allows the enabled alert service to process that backlog, so an email may refer to an earlier delivery failure. Removing the recipient prevents sending to that address; it does not clear pending alerts.

Investigate an alert¶

1. Review the affected subscription and your receiving endpoint's logs. Check endpoint availability, authentication verification, and whether accepted requests receive a 2xx response.
2. Correct the receiving endpoint's problem and inspect subsequent delivery results. Follow Receiving Events for acknowledgment and duplicate-processing requirements.
3. Reconcile any missing notifications with your own transaction records before repeating a business action. An alert does not establish that a payment failed or authorize submitting it again.

Alert emails do not include webhook payloads, signing secrets, or endpoint query strings. Keep credentials and customer payloads out of email replies and support attachments.

Verify the configuration¶

Confirm the saved recipient in Portal and verify that the intended team can access that mailbox. When a real retryable delivery failure exhausts its attempts, compare its recorded delivery status with the alert received by that mailbox. Saving an address alone does not prove end-to-end email delivery.