SigFollow
Sign in

System guide

Webhooks

From Integration Settings → Webhooks, configure callback URLs to receive system event notifications — including message delivery status, template status changes, and inbound messages.

Adding a webhook

Click Add webhook, fill in the dialog, and save to enable the webhook.

What to fill in

  • Webhook URL — where events are delivered. It must start with http:// or https:// and be at most 512 characters. If it does not, you will see URL must start with http:// or https://. Use https:// in production.
  • Enable immediately after saving — a checkbox that turns the webhook on right away. Leave it unchecked to save the configuration without starting delivery yet.

Click Save. Once the webhook is added, a signing secret is generated and shown to you (see Verifying signatures below).

Choosing which events to receive

Below the configuration card, the Subscribed events card lists the events available for subscription. Toggle on the ones you want your service to receive.

EventFieldWhat you receive
Message statusstatusessent / delivered / read / failed — the lifecycle of your outbound messages
Inbound messagesmessagesRaw user messages in original Meta format (text, media ids, interactive replies)
Template statustemplate_statusMeta template review events (APPROVED / REJECTED / PAUSED / …)
Sensitive events stream business content
Turning on Inbound messages means the actual text, media, and interactive replies your customers send are forwarded to your endpoint. Only subscribe to it if your receiver handles that data securely.

Downloading media from inbound messages

When a customer sends an image, video, audio file, or document, SigFollow downloads the file from Meta and stores it for you. The inbound message then carries an extra sigfollow_media object alongside Meta's original fields:

{
  "id": "wamid.HBgLODUyNTc0OTcwMDIVAgASGBQzQTdENUY1NTg0M0JDQ0FGMDA1QwA=",
  "from": "85257497002",
  "timestamp": "1784734351",
  "type": "image",
  "image": {
    "id": "1484623427030995",
    "mime_type": "image/jpeg",
    "sha256": "ku9EPXghCUR84ZNWwfL8H9Qic4viqB27OdZUFIBnK7s="
  },
  "sigfollow_media": {
    "url": "https://api.example.com/public/media/message/58d5027a-ee3f-4e39-bd58-023da51858f0.jpg?exp=1785339156&sig=55eba1e16a13283c5bcb198b45a7c21d247357282816df7af6b4ab979072b009",
    "expires_at": 1785339156
  }
}
  • url — download it with a plain GET. No authentication header is required; the credential is the signature carried in the URL itself.
  • expires_at — Unix timestamp (seconds) at which the link stops working. Links are valid for 7 days by default.
Save the file before the link expires
Once expires_at has passed, the URL returns 404 and cannot be renewed — and the original message is not re-delivered. Copy the bytes into your own storage as soon as you receive the event.

Things to watch for

  • Do not alter any part of the URL. The exp and sig query parameters are signed together, so changing either one returns 404.
  • The object appears only for media messages whose file was downloaded successfully. Text and interactive messages never carry it.
  • If Meta re-delivers the same message, the duplicate delivery may omit this object. Deduplicate on the message id and keep the first event that carried sigfollow_media.

Verifying signatures

Every request SigFollow sends carries an X-Hub-Signature-256 header. The value is sha256= followed by the hex-encoded HMAC-SHA256 of the raw request body, keyed with your signing secret. Your Signature verification is optional, but recommended for security.

Where the signing secret comes from

The secret is generated the first time you enable the webhook and again whenever you click Rotate secret.

The secret is shown only once
SigFollow does not store the secret, so it cannot be displayed again after it is generated. If you lose it, use Rotate secret to issue a new one — but rotating invalidates the old secret, so update your receiver right away or signature verification will fail if enabled.

Testing your endpoint

Click Send test to deliver a sample payload synchronously and see the result inline. The result card shows the HTTP status and round-trip time — for example HTTP 200 · 123ms on success, or HTTP 500 / Network error on failure. It also shows the X-Hub-Signature-256 header that was sent and a Show payload link to inspect the full JSON, which makes it easy to confirm your signature check works end to end. Click Dismiss to close the card.

Delivery and retries

After receiving a webhook request, your server should return an HTTP 200 response as quickly as possible to acknowledge delivery. Otherwise, SigFollow retries the delivery several times before giving up. Keep your handler fast and idempotent: deliveries can arrive more than once, so deduplicate on the message or status id in the payload.

Webhook request format reference

Because payloads are forwarded in the unchanged Meta Cloud API webhook shape, the field reference is Meta's own webhook documentation. For the signature scheme and authentication details as they apply across the platform, see the API authentication and integrations chapters of this guide.

PreviousAPI keys