Post-Hook Notifications

Webhookd can send a notification with the results of a script execution after it completes. This is useful for being alerted to successful deployments, failures, or other significant events.

Notifications are configured globally via the WHD_NOTIFICATION_URI environment variable or the --notification-uri flag.

How It Works

To trigger a notification, your script must output lines that begin with a specific prefix. By default, the prefix is notify:.

  • If one or more lines in your script's output match the prefix, a notification will be sent.
  • If no lines match the prefix, no notification is sent.
  • The content of the notification will be all the matching lines, with the prefix removed.

Example Script: 

#!/bin/bash

echo "Doing some work..."
echo "notify: Deployment to staging was successful!"
_date=$(date)
echo "notify: Completed at ${_date}"
echo "This line will not be in the notification."

The notification sent for this script would contain: 

Deployment to staging was successful!
Completed at <current date>

You can customize the prefix by adding a prefix query parameter to the notification URI, for example: --notification-uri="http://my.service?prefix=ALERT:".

Supported Channels

Webhookd supports two primary notification channels: HTTP and Email.

HTTP Notification

This method sends a POST request with a JSON payload to the specified HTTP or HTTPS URL.

  • Configuration URI: http://example.com/webhook or https://example.com/webhook

JSON Payload Structure: The following JSON is sent to the target URL: 

{
  "id": "42",
  "name": "my-hook-name",
  "text": "The notification content from the script...\nMore content...\n",
  "error": "Error cause... if present"
}

This payload structure is compatible with incoming webhooks for services like:

This makes it easy to send script results directly to your team's chat channels.

Email (SMTP) Notification

This method sends the notification content as an email.

  • Configuration URI: mailto:user@example.com

All additional configuration is provided via query parameters in the URI.

Configuration Options:

Parameter Description Default
smtp The SMTP host and port to use. localhost:25
username The username for SMTP authentication. (none)
password The password for SMTP authentication. (none)
conn The SMTP connection security type. Can be plain, tls, or tls-insecure. plain
from The sender's email address. noreply@nunux.org
subject The email subject line. [whd-notification] {name}#{id} {status}

Subject Template Variables:

  • {name}: The name of the hook.
  • {id}: The unique ID of the hook execution.
  • {status}: The final status of the execution (success or error).

Example URI: To send an email to ops@example.com via an external SMTP server requiring TLS and authentication: 

mailto:ops@example.com?smtp=mail.example.com:587&conn=tls&username=myuser&password=mypassword&from=webhookd@example.com