Webhooks
Receive signed events when a message is sent, delivered or fails, or a contact opts in or out.
Webhooks push an event to your endpoint as it happens, so you do not have to poll. Each delivery is signed with Standard Webhooks, so your receiver can verify it came from VYG and was not changed in transit.
See the Webhooks reference for the full input and response of every endpoint. The Webhooks guide has every event payload and code samples to verify and handle deliveries.
Who can call this
An API key that includes webhooks:manage, or a sign-in token of a brand admin who asked for it. Create a key in Settings → API
keys with Write access to Webhooks; a Read-only key does not include it. Keep the API key server-side; never ship it in browser code. Webhook management is REST only
and is not exposed as an MCP tool.
The feature is turned on per brand with the beta:messaging-api permission. Without it the endpoints
answer 403 feature_not_enabled. If a request returns 403 insufficient_scope, add webhooks:manage
to the key.
One endpoint per brand
A brand has one webhook endpoint. All management calls act on it at /v1/webhooks; there is no endpoint
id. Creating a second endpoint answers 409 conflict: update the existing one, or delete it first.
Events
The endpoint subscribes to one or more event types. The available types are:
| Event | When it fires |
|---|---|
message.received | A contact replies to the brand. |
message.sent | An outbound message is accepted for sending. |
message.delivered | The carrier confirms delivery. |
message.failed | Sending or delivery failed. |
contact.opted_out | A contact opts out (for example, replies STOP). |
contact.opted_in | A contact opts back in. |
A webhook.test event is sent when you call the test endpoint, through the same signed delivery path.
By default a payload does not include the contact phone number. Set include_phone on the endpoint to
add it; that needs the contacts:read-phone permission and is recorded in the audit log. Changing the
URL of an endpoint that already includes the phone number needs the same permission.
An event is sent only for changes that happen after the endpoint was created, and after its last settings change (URL, event types, phone number or enabled state). Re-enabling a disabled endpoint does not send the events it missed while it was off.
Create the endpoint
curl -X POST "https://api.vyg.app/v1/webhooks" \
-H "Authorization: Bearer $VYG_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/hooks/vyg",
"event_types": ["message.delivered", "message.failed"]
}'The response returns the endpoint and its signing secret (whsec_…) exactly once:
{
"url": "https://example.com/hooks/vyg",
"event_types": ["message.delivered", "message.failed"],
"enabled": true,
"include_phone": false,
"disabled_reason": null,
"created_at": "2026-11-10T15:00:00.000Z",
"updated_at": "2026-11-10T15:00:00.000Z",
"secret": "whsec_…"
}Store the secret in your own secret manager. It is never shown again; if you lose it, rotate it.
Read the endpoint with GET /v1/webhooks, change it with PATCH /v1/webhooks, and remove it with
DELETE /v1/webhooks.
Verify a delivery
Each delivery carries three headers: webhook-id (the event id, constant across retries so you can
dedupe), webhook-timestamp (unix seconds), and webhook-signature (one or more space-separated
v1,<signature> tokens). The signature is the base64 HMAC-SHA256 of
${webhook-id}.${webhook-timestamp}.${raw-body} under your signing secret. Verify against the exact
bytes you received, not a re-serialized body. Any Standard Webhooks library verifies these headers.
Delivery is at least once: on rare occasions the same event can arrive twice. Use webhook-id to
ignore a repeat.
Retries
Any 2xx response within 15 seconds counts as delivered. Any other response, a timeout or a
connection error is retried. An event gets up to 10 attempts over about 3 hours:
| Attempt | Wait before it |
|---|---|
| 1 | none |
| 2 | 30 seconds |
| 3 | 2 minutes |
| 4 | 5 minutes |
| 5 | 10 minutes |
| 6 | 15 minutes |
| 7 | 20 minutes |
| 8 | 30 minutes |
| 9 | 45 minutes |
| 10 | 50 minutes |
After the last attempt the event is dropped. If your endpoint accepted no delivery at all during that
window, it is disabled with disabled_reason sustained_delivery_failure. A 410 Gone response
disables it at once with endpoint_returned_410. Turn it back on with
PATCH /v1/webhooks and {"enabled": true}.
Event payloads are kept for 4 days, then deleted. Delivery history is not stored, so there is no delivery log or replay.
Rotate the signing secret
Rotating returns a new secret and keeps the previous one valid for 24 hours, so you can roll your receiver without missing a delivery:
curl -X POST "https://api.vyg.app/v1/webhooks/rotate-secret" \
-H "Authorization: Bearer $VYG_API_KEY"During the overlap the signature header carries one token per active secret, so a receiver that holds either secret verifies.
Send a test
Send a signed webhook.test event to confirm your signature check and connectivity. The endpoint must
be enabled:
curl -X POST "https://api.vyg.app/v1/webhooks/test" \
-H "Authorization: Bearer $VYG_API_KEY"The response is 202 with the test's event_id; the event then arrives through the normal delivery
path and retries.
Failures
| Status | error.code | When |
|---|---|---|
400 | bad_request | The body is invalid: the URL is missing, or an event type is unknown. |
400 | invalid_webhook_url | The URL is not HTTPS, has credentials, or does not resolve to a public address. |
403 | feature_not_enabled | The brand does not have the beta:messaging-api permission. |
403 | insufficient_scope | The credential lacks webhooks:manage, or include_phone was set (or a phone-bearing endpoint's URL changed) without contacts:read-phone. |
404 | not_found | The brand has no webhook endpoint. |
409 | conflict | The brand already has an endpoint (create), or the endpoint is disabled (send test). |