deliverhook - Documentation

What are webhooks?

Webhooks are a way for applications to communicate with each other in real time. Instead of constantly checking (or "polling") for updates, a webhook automatically sends data to another system when a specific event happens.

For example, if a payment is completed on a website, a webhook can immediately notify another service (like an invoicing system) by sending an HTTP request to a predefined URL. This makes webhooks efficient and fast for triggering automated actions across systems.

How deliverhook delivers webhooks requests

Once an email is received by deliverhook, it is parsed and converted into a JSON structure. The JSON payload is then sent via HTTP POST to your defined webhook endpoint. Delivery usually happens in under 60 seconds.

You can configure retry logic in case your server is temporarily unavailable. We support retrying on specific HTTP status codes (like 5xx or 4xx), connection timeouts, and more. You can also inspect and resend individual messages manually from the dashboard.

Webhook Payload

Every time an email is received, deliverhook will POST a webhook to your configured endpoint. The following table and JSON describe what the payload looks like and what each field means.

subject string

The subject line of the email.

date string (RFC 2822)

Timestamp when the email was received.

html nullable string

HTML version of the email body, if available.

text string

Plain-text version of the email body.

from object

Information about the sender.

name – Sender's name
address – Sender's email address

attachments array

A list of attachments in the email.

filename – Name of the attachment file
content_type – MIME type of the file
size – File size in bytes
url – Temporary signed download URL

Example Payload

{
  "subject": "Invoice for March 2025",
  "date": "Mon, 17 Mar 2025 14:32:00 +0000",
  "html": null,
  "text": "Hi,\n\nPlease find attached the invoice for March 2025...",
  "from": {
    "name": "John Doe",
    "address": "john.doe@example.com"
  },
  "attachments": [{
    "filename": "invoice_29110.pdf",
    "content_type": "application/pdf",
    "size": 123871,
    "url": "https://deliverhook/api/attachment/jse23sh19"
  }]
}

Consuming Webhooks in Your Code

Below are examples in common programming languages to help you quickly build an endpoint that listens for and processes incoming deliverhook webhooks.

const express = require('express');
const app = express();
app.use(express.json());

app.post('/webhook', (req, res) => {
  const data = req.body;
  console.log('Received email:', data.subject);
  res.status(200).send('OK');
});

app.listen(3000, () => console.log('Server running on port 3000'));

from flask import Flask, request, jsonify
app = Flask(__name__)

@app.route('/webhook', methods=['POST'])
def webhook():
    data = request.get_json()
    print('Received email:', data['subject'])
    return '', 200

if __name__ == '__main__':
    app.run(port=3000)

<?php
$input = json_decode(file_get_contents('php://input'), true);
file_put_contents('email.log', print_r($input['subject'], true));
http_response_code(200);

Handling Attachments

If an email contains attachments, they will be included as an array in the payload. Each attachment will have a direct URL for downloading. Make sure your server or script handles these securely and appropriately, especially if you are storing or processing the files.

Securing Your Webhook Endpoint

Because your webhook endpoint is exposed to the internet, anyone could potentially send requests to it. To ensure that a request genuinely comes from deliverhook, every webhook request is cryptographically signed using a SHA256 HMAC.

The signature is included in the X-Signature HTTP header. You can use this to verify the integrity and authenticity of the request.

To verify the signature, you’ll need your shared signing secret, which can be found on the webhook details page under the Security tab.

You can verify the signature with code like this in JavaScript:

const crypto = require('crypto');

const secret = 'our shared secret';
//Please note you need the raw payload as sometimes parsers can introduce
//slight differences in the payload.
const payload = 'the JSON payload from our request'
const header = 'the X-Signature header value from our request'

const hash = crypto
  .createHmac('sha256', secret)
  .update(payload)
  .digest('hex');

if (hash === header) {
  console.log('request is verified!')
}

PHP example:

<?php

$payload = json_decode('the JSON payload from our request');

$secret  = 'our-shared-secret';
$header  = 'the X-Signature header value from our request';

$sha = hash_hmac('sha256', json_encode($payload), $secret);

if ($sha === $header) {
    echo 'request is verified!';
}

Need Help?

Reach out to our team at support@deliverhook for technical support, feature requests, or bug reports.

deliverhook Documentation