Errors and retries
Understand webhook responses and retry failed deliveries.
Check the HTTP status before deciding whether to retry. Read reason and details, when
present, to identify fields that need correcting.
Status codes
| Status | Meaning | Next step |
|---|---|---|
200 | ok: true means accepted; deduplicated: true acknowledges a repeated delivery. ok: false with reason: "dead_letter" means processing failed. | Stop retries. Contact support for dead_letter; otherwise check campaign activity separately. |
400 | Empty body, missing required body fields, invalid JSON, or an invalid payload. | Correct the request and resend. A new event_id is not required. |
401 | Authentication failed. | Check the data source's security check and credentials. For HMAC, sign the exact body bytes you send. |
404 | The integration is unavailable, or the event type is not registered and enabled. | Check the URL, integration and event definition, then resend. |
422 | The identifier mapping found no entity ID or contact channel, or a resolved email/phone conflicts with another contact. Email alone is accepted for ingest (and email flows); SMS/agent still need phone. | Supply an entity ID and an email or phone number, update the mapping, or resolve a contact_channel_conflict. |
500, 503 | VYG could not complete the request. | Retry with backoff. |
For signing examples, see HMAC verification.
For 400 and 422 details, see Custom Events.
Retry policy
Retry 5xx responses with exponential backoff and jitter. For example, wait 1 second,
5 seconds, 30 seconds, 5 minutes, then progressively longer intervals up to your delivery deadline.
Stop automatic retries on 2xx. If the body contains ok: false and reason: "dead_letter",
the event could not be processed; contact VYG support with the event ID. Correct a 4xx
request before sending it again.
Keep the same event_id, x-vyg-event-id and body when retrying an unchanged delivery.
After correcting a rejected payload or enabling its event definition, you can reuse the
same delivery ID.
Entity IDs and delivery IDs
event_id identifies a delivery. The stable ID selected by external_id_path identifies
the entity represented by the event, such as a checkout or order. Deliveries for the same
entity and event definition refer to the same saved record. Changing only the delivery ID
does not create a new entity.
Use a different entity ID only for a genuinely different entity. See Identifier mapping.