Skip to content
  • There are no suggestions because the search field is empty.

SMS Webhooks

How to use GoFax SMS webhooks natively to get notified of SMS reply or receive events.

Webhooks let GoFax notify your application in real time when something happens—without you polling the API. When an event (like an SMS reply or an inbound SMS) occurs, GoFax sends an HTTPS request to the Webhook URL you provide. Your system receives that payload and can act on it immediately (e.g., create a helpdesk ticket, trigger a workflow, or post a message in a chat tool).

Webhooks are ideal when you need immediate updates, low overhead, and event-driven automation.

Note: If you previously combined GoFax API with external webhook processors, this article covers the new native webhook capability, which removes the need for a third-party relay.

Native SMS webhooks deliver JSON payloads to your HTTPS endpoint and support an optional Signing Secret for request verification.

Typical Use Cases

  • Update conversation threads in tools like HubSpot, Zendesk, or MS Teams via your middleware.
  • Trigger notifications/workflows (e.g., forward to a shared inbox, start an approval flow, or kick off sentiment analysis) as soon as messages arrive.
  • Archive and analytics: push events to a data pipeline for reporting.

Before You Start

  • A publicly reachable HTTPS endpoint that can accept POST requests.
  • Ability to return an HTTP status code (e.g., 200 OK) promptly.
  • Optional: capability to verify an HMAC Signing Secret header for security (recommended).

Add a New Webhook

  1. Go to My Account → Webhooks.
  2. Click Add a New Webhook.
  3. Webhooks let GoFax notify your application in real time when something happens—without you polling the API. When an event (like an SMS reply or an inbound SMS) occurs, GoFax sends an HTTPS request to the Webhook URL you provide. Your system receives that payload and can act on it immediately (e.g., create a helpdesk ticket, trigger a workflow, or post a message in a chat tool).
  4. Events: select one or both:
  5. Include Message body (labelled Include Content on the Add screen):
  6. Click Save.

Fields you’ll see

  • Webhooks let GoFax notify your application in real time when something happens—without you polling the API. When an event (like an SMS reply or an inbound SMS) occurs, GoFax sends an HTTPS request to the Webhook URL you provide. Your system receives that payload and can act on it immediately (e.g., create a helpdesk ticket, trigger a workflow, or post a message in a chat tool).
  • Events: select one or both:

  • Profile Status – Active or Inactive.
  • Created Date / Last Update Date – audit trail.
  • Include Message body (labelled Include Content on the Add screen):
  • Optional: capability to verify an HMAC Signing Secret header for security (recommended).

Delivery Logs & Resend

The Webhook Log shows a record of delivery attempts, timestamps, and statuses. From an individual event log entry, you can Resend to retrigger delivery by selecting the Actions Button ., and confirming. This is useful if your endpoint was down or you need to replay the event for testing.

⚠️ Important: Resending can duplicate the event on your system. Ensure your application is idempotent—use a unique event/message ID to deduplicate.

Event Payloads (What Your Endpoint Receives)

GoFax posts a JSON payload to your Webhook URL using HTTP POST. While payloads may evolve, they generally include:

{
  "eventType": "SMS_REPLY",  
  "eventTimestamp": "2025-12-04T00:24:07.112733Z",  
  "messageId": "abc123",  
  "direction": "reply",  
  "from": "+61400000000",  
  "to": "+61700000000",  
  "messageBody": "Thanks for your message",  
  "metadata": { "accountId": "12345" },  
  "signature": "HMAC_SHA256"  
}

Securing Your Webhook Endpoint

  • Use HTTPS and a valid certificate.
  • Verify the signature: if you set a Signing Secret, validate the X-GoFax-Signature (or equivalent header) on each request before processing.
  • Implement idempotency: ignore duplicates based on messageId.
  • Respond fast: return 2xx quickly, then process asynchronously if needed.
  • Log requests: capture headers, status, and IDs for troubleshooting.

Testing Tips

  • On the Webhook Detail page, click Test to simulate a delivery. Confirm that your endpoint logs the call and returns 200.
  • Use your application logs to verify signature validation and payload parsing.
  • The Webhook Log shows a record of delivery attempts, timestamps, and statuses. From an individual event log entry, you can Resend to retrigger delivery by selecting the Actions Button and confirming. This is useful if your endpoint was down or you need to replay the event for testing.

  • If you don’t see entries, check the Webhook Log and your firewall/ingress rules.

Troubleshooting

  • No history found in Webhook Log: ensure the webhook is Active and events are selected.
  • 4xx/5xx responses: your endpoint rejected or failed. Validate URL, auth, and payload handling.
  • Duplicates after Resend: add idempotency checks using messageId.
  • Not receiving message body: enable Include Message body in the webhook settings.

Legacy (form-data) SMS delivery notifications

For SMS send status notifications, the legacy webhook posts URL-encoded form-data including keys such asRecipient,ID,Success, andMessage. Configure this under Send SMS Service → Manage SMS Settings → General SMS Settings.

FAQs

Can I subscribe to multiple events with one webhook?

Yes - hold Ctrl/Cmd to select multiple events when editing.

Can I pause deliveries?

Make Active / Inactive: toggle whether the webhook is currently delivering events.

Can I see what was delivered?

Open Log: view the delivery history for this webhook.