Webhooks are a way to receive HTTP POST requests from Hyvor Relay when certain events occur. They are useful to sync state (email sending status) between Hyvor Relay and your application or to trigger actions in your application based on events in Hyvor Relay.
send.recipient.accepted is triggered when an email is accepted by the recipient
SMTP server. This can be triggered once for a recipient of a send. It indicates that the email
has been successfully delivered to the recipient's server, but it does not guarantee that the
email has been delivered to the recipient's inbox. send.recipient.bounced or send.recipient.complained can be triggered later if the email is not delivered to the
recipient's inbox (ex: when the mailbox is full, or if the email provider's spam detector detects
the mail as spam) or if the recipient marks it as spam.
{
send: Send;
recipient: SendRecipient;
attempt: SendAttempt;
}Objects: Send, SendRecipient, SendAttempt
send.recipient.deferred is triggered when an email is temporarily deferred by the
recipient SMTP server. This can happen for various reasons, such as the recipient's server being
busy or because of greylisting.
Hyvor Relay will retry sending the email a few more times before giving up. You can expect a send.recipient.accepted or send.recipient.bounced event later.
{
send: Send;
recipient: SendRecipient;
attempt: SendAttempt;
}Objects: Send, SendRecipient, SendAttempt
send.recipient.bounced is triggered when an email is permanently rejected by the recipient
SMTP server. This can happen for various reasons, such as the recipient's email address not existing
or the recipient's server rejecting the email due to spam filters.
send.recipient.bounced event is triggered immediately.send.recipient.accepted event is
triggered first, followed by the send.recipient.bounced event when the bounce is
detected.If we detect a hard bounce (permanent failure) for a send, the email address is automatically added to your project's suppression list. This means that you cannot send emails to that email address again unless you manually remove it from the suppression list. This is to prevent sending emails to invalid email addresses, which can harm your sender reputation.
{
send: Send;
recipient: SendRecipient;
attempt: SendAttempt | null;
bounce: Bounce;
}Objects: Send, SendRecipient, SendAttempt Bounce
When a recipient marks an email as spam, the email provider sends a complaint, called a Feedback
Loop (FBL), to Hyvor Relay. Hyvor Relay is configured to receive FBLs from major email
providers.bind: We process these complaints and trigger the send.recipient.complained event. This event indicates that the recipient has marked the email as spam or junk. When this
event is triggered, the email address is automatically added to your project's suppression list,
similar to when a hard bounce occurs.
{
send: Send;
recipient: SendRecipient;
complaint: Complaint;
}Objects: Send, SendRecipient, Complaint
This event is triggered when an email is not sent to a recipient because the recipient was previously added to the suppression list. This means that the email was automatically marked as suppressed without trying to send it. No further events will be triggered for this recipient.
{
send: Send;
recipient: SendRecipient;
suppression: Suppression;
}Objects: Send, SendRecipient, Suppression
This event is triggered when an email could not be sent to a recipient after multiple attempts due to network or server issues. No further events will be triggered for this recipient.
Note: This is different from a bounce. A bounce indicates that the recipient's server rejected the email, while a failure indicates that the email could not be sent due to other issues. Failed emails are not added to the suppression list automatically.
{
send: Send;
recipient: SendRecipient;
attempt: SendAttempt;
}Objects: Send, SendRecipient SendAttempt
This event is triggered when a new domain is created in your Hyvor Relay project.
{
domain: Domain;
}Objects: Domain
This event is triggered when the status of a domain changes.
{
domain: Domain;
old_status: 'pending' | 'active' | 'warning' | 'suspended';
new_status: 'pending' | 'active' | 'warning' | 'suspended';
dkim_result: {
verified: boolean;
checked_at: number;
error_message: string | null;
}
}Objects: Domain
This event is triggered when a domain is deleted from your Hyvor Relay project.
{
domain: Domain;
}Objects: Domain
This event is triggered when a suppression is created for an outgoing email. This could either
be due to a hard-bounce or a complaint.
{
suppression: Suppression;
}Objects: Suppression
This event is triggered when a suppression is deleted from your Hyvor Relay project.
{
suppression: Suppression;
}Objects: Suppression
When Hyvor Relay sends a webhook, it expects a 2xx HTTP response code from your
application. If it does not receive a 2xx response, it will retry sending the webhook
up to 6 times with the following intervals between retries:
If all retries fail, the webhook delivery will be marked as failed, and you can view the delivery status in the Hyvor Relay Console, including the error message received from your server.
When creating a webhook, a secret key is generated. This will be used to sign the webhook
requests. You can then verify the signature of the request to make sure it's coming from Hyvor
Relay. The signature is a HMAC-SHA256 hash of the request JSON body. The secret key is used as
the key. To validate, you should generate a signature using the same algorithm, the given
request body, and the secret key. Then, compare the generated signature with the signature in
the X-Signature header. If they match, the request is valid.