- from: the from address
- to: the to address
- subject: the subject line
- body: email body. We plan to make email inline attachment body point to atttachment id soon. Stay tune
- headers: an array of key value of header
Webhook turns the incoming email into a HTTP post to your URL of choice. It enables your application to react to incoming email in a HTTP service, we will handle the heavy lifting of handling incoming email, parse the email into a JSON document, and send it to your HTTP endpoint.
Note that when using webhook, it has a short amount of time we will store your email on disk (with full encryption at rest) to queue the email for our webhook worker to post to your endpoint. If for any reason, that your endpoint is down or returns a 5xx error, we will retry sending your webhook until success(received a 2xx or 3xx response). Upon succesfully posting data to your webhook, your email will be removed. If your webhook is down for more than 7 days, we will stop retrying and delete the email from our job queue.
To use webhook, from the dashboard, go to your domain detail page, and then click on "Webhook tab". On that page, you will be able to add a URL for your webhook. If your webhook needs an API key or custom header authentication, or content type, etc, you can add those header by clicking on "Add header" and then enter your header name and header value.
You can add as many webhook as you want, and we will post your email to all of them.
We delete your email from the job queue upon successfully posting it to your webhook. If your webhook is down or returns a 5xx error, we will re-trying the post up to 7 days. However, even after 7 days and we still cannot deliver your webhook, we will delete the email and notify you about the error.
By default, you can use wildcard `*` to match all email and create webhook request. However, you can also limit webhook email scope to a single email or a regex.
In this example, only email send to firstname.lastname@example.org will cause a webhook request
In this example, only email send to email@example.com will cause a webhook request
Because email can has attachments, so we're using multipart/form-data content type, post as a form to your webhook endpoint. You can use a site like webhook.site or ngrok to test out and inspect request payload during development
An example of how we use webhook is http://pix.fastloop.xyz/, a service that you send an image and it will be hosted on our platform. The code is available on our Github account.
This is how webhook configuration look like for this sample service: