VYG Docs
Concepts

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:

EventWhen it fires
message.receivedA contact replies to the brand.
message.sentAn outbound message is accepted for sending.
message.deliveredThe carrier confirms delivery.
message.failedSending or delivery failed.
contact.opted_outA contact opts out (for example, replies STOP).
contact.opted_inA 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:

AttemptWait before it
1none
230 seconds
32 minutes
45 minutes
510 minutes
615 minutes
720 minutes
830 minutes
945 minutes
1050 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

Statuserror.codeWhen
400bad_requestThe body is invalid: the URL is missing, or an event type is unknown.
400invalid_webhook_urlThe URL is not HTTPS, has credentials, or does not resolve to a public address.
403feature_not_enabledThe brand does not have the beta:messaging-api permission.
403insufficient_scopeThe credential lacks webhooks:manage, or include_phone was set (or a phone-bearing endpoint's URL changed) without contacts:read-phone.
404not_foundThe brand has no webhook endpoint.
409conflictThe brand already has an endpoint (create), or the endpoint is disabled (send test).

On this page