Run a Twilio SMS Gateway with Signature Validation

SMS reaches users almost everywhere, but it has costs, identity limits, and an internet-facing webhook. Hermes requires the configured webhook URL to match the URL Twilio signs. Treat that exact match and a narrow E.164 sender policy as hard launch gates.

Official documentation: https://hermes-agent.nousresearch.com/docs/user-guide/messaging/sms

Configure both ends as one contract

Collect the Twilio Account SID, Auth Token, and an SMS-capable phone number. Store the Auth Token as a secret. Run hermes gateway setup, select SMS, and configure the number and webhook settings. In the Twilio console, set the incoming-message webhook to the documented Hermes SMS path using HTTPS.

The public webhook URL used by Hermes must exactly match the URL configured at Twilio so request-signature validation can succeed. Hostname, scheme, path, and proxy behavior all matter. A rotating tunnel is fine for a short development test but unsuitable for unattended production delivery.

Launch checklist

Confirm the Twilio number supports the required messaging region.
Store the Account SID and Auth Token securely.
Establish a stable public HTTPS webhook.
Configure the identical webhook URL in Hermes and Twilio.
Restrict allowed senders with E.164 phone numbers.
Choose a fixed SMS home target for scheduled delivery if appropriate.
Set cost, frequency, and message-length expectations.
Test inbound, outbound, and failure-status behavior.
Review applicable consent and messaging-compliance requirements.

Respect SMS constraints

Phone-number ownership is not perfect identity assurance, and messages may be visible on lock screens or shared devices. Do not send secrets or sensitive customer data. Long output may split into multiple billed segments and arrive out of order. Summarize first and link to a secure destination when a report is large.

Inbound acceptance and outbound delivery are separate states. Track provider delivery statuses rather than interpreting an accepted API request as proof the handset received the message.

Common pitfalls

Configuring a different webhook URL in Twilio and Hermes.
Disabling signature checks to make a temporary tunnel work.
Using local phone-number formatting instead of E.164.
Treating a phone number as strong authentication for privileged tools.
Sending large reports as expensive multipart messages.
Ignoring opt-in, opt-out, regional, or application-to-person messaging rules.

Verification steps

Start the adapter and confirm signature validation is enabled.
Send an inbound SMS from an allowed number and verify the correct reply.
Send from an unauthorized number and confirm policy behavior.
Change one character in a controlled webhook test and verify invalid signatures are rejected.
Inspect the Twilio delivery status for an outbound response.
Test a message near the segment boundary and review cost and readability.
Review logs for full tokens, excessive phone-number exposure, replayed requests, and delivery failures.