Webhook setup
Install a receiver, verify signed publishing updates and send a safe test.
Receiving contract
Use one receiver and signing key per workspace subscription. Nuntio sends a JSON body with Nuntio-Event, Nuntio-Timestamp and Nuntio-Signature headers. Store the key on the server. Read the exact request bytes before parsing the body. The workspace ID is the UUID in the workspace URL.
Verify before acting
Verify each request before parsing it or sending a chat message.
- Read the exact body bytes. Build the signed value from nuntio.webhook.v1, Nuntio-Timestamp, Nuntio-Event and the raw body, joined with newline characters.
- Calculate HMAC-SHA256 with the workspace signing key. Compare its hexadecimal digest with the v1 value in Nuntio-Signature using a constant-time comparison.
- Reject timestamps more than five minutes from the server’s current time. Match Nuntio-Event to event_id and the configured workspace to account_id.
- Record the accepted event ID durably before applying an effect. Preserve that record across restarts so a duplicate update does not send another message.
Wrong signatures return 401; invalid data returns 422. Nuntio does not retry these responses. Only network failures, HTTP 429 and HTTP 5xx qualify for automatic retry. Correcting the receiver does not automatically replay an old failed delivery.
Receiver example
Download the Ruby Rack receiver and server configuration into one private directory. The receiver supports Slack and Discord incoming webhooks. It verifies signatures and workspace identity, records event IDs on disk, then forwards a short status message. Discord sends disable all mentions. Both recipes have offline HTTP-contract tests; no live Slack or Discord delivery is claimed.
Run and test
Use Ruby 4 with Rack and Puma installed. Run the receiver behind HTTPS with durable, private local storage. Start with a test Slack or Discord channel.
- Download Receiver, Server and Sample into one private directory. The Server file is config.ru; keep the receiver and sample filenames supplied by the downloads.
- Set NUNTIO_SIGNING_KEY to the key shown once when the Nuntio webhook is created. Set NUNTIO_WORKSPACE to the workspace UUID from its URL.
- Set NOTIFICATION_WEBHOOK to the private Slack or Discord incoming-webhook address. Set NUNTIO_RECEIPTS to a private file on durable local storage.
- Start the receiver with the command below and expose its /nuntio route through HTTPS. Register that HTTPS address in Nuntio → Settings → Webhooks.
- Set NUNTIO_RECEIVER to the receiver’s HTTPS /nuntio address. Run ruby sample.rb --send published, then ruby sample.rb --send uncertain.
- Check the test chat channel. Both messages start with Test and each should appear once. A receiver response alone does not prove chat delivery.
puma -b tcp://127.0.0.1:9292 config.ru
Use synthetic events for this check. A real social post is not needed to test the receiver.
Recovery and storage
Keep the receipt file private and back it up. Do not run multiple hosts against separate copies. Once an event is claimed, the example never forwards it automatically again, including after a timeout or crash. Inspect claimed or needs_check receipts and the chat channel before any manual action. A 202 response means the receiver retained the event, not that chat delivery succeeded. There is no automatic pruning or replay. For higher volume, move receipts to your own database and define retention before enabling it.