Webhook Targets

Seatmap.pro can notify your own systems when venues, schemas and seatmaps change. This page covers what a webhook target must look like and what happens when a delivery fails.

Events

Event	Sent when
`venue.created`	A venue is created.
`venue.updated`	A venue is changed.
`venue.deleted`	A venue is deleted.
`schema.created`	A schema is created.
`schema.updated`	A schema is changed.
`schema.deleted`	A schema is deleted.
`seatmap.stored`	A seatmap is saved.

Target requirements

Breaking: from 1.70.0 a webhook target must be a public HTTPS destination. A target that does not meet both conditions is rejected when you save it, and any delivery to it is recorded with the error type TARGET_NOT_ALLOWED.

A target is accepted when:

The URL is a valid URI with a host.
The scheme is https. Plain http is rejected.
Every address the host resolves to is publicly routable.

A host is rejected when any of its addresses is loopback, link-local, site-local (private ranges such as 10.0.0.0/8, 172.16.0.0/12 and 192.168.0.0/16), multicast, carrier-grade NAT, or otherwise reserved. IPv6 unique-local addresses are rejected too, as are IPv4-mapped IPv6 addresses whose underlying IPv4 address is blocked. A host that cannot be resolved at all is rejected.

If your endpoint is not public

Terminate TLS on a public hostname and forward internally from there — a reverse proxy or an API gateway in front of your service is enough. Do not expect an internal hostname to work because it resolves publicly to a private address; the check is on the resolved address, not the name.

Self-hosted deployments that genuinely need to deliver inside their own network can set seatmap.webhooks.allow-private-targets to true on the editor service. This turns the address check off, so enable it only when the whole network path is under your control.

Retries

A failed delivery is retried with exponential backoff, three times by default. The defaults are:

Setting	Default	Meaning
`timeoutMs`	`30000`	Per-attempt timeout.
`maxRetries`	`3`	Retries after the first attempt.
`backoffInitialMs`	`1000`	Delay before the first retry.
`backoffMultiplier`	`2.0`	Multiplier applied to each subsequent delay.
`retryOnHttpStatuses`	`500, 502, 503, 504`	Statuses that are retried.
`skipRetryOnHttpStatuses`	`400, 401, 403, 404`	Statuses that are treated as final.

Timeouts, network errors and connection errors are retried. A TARGET_NOT_ALLOWED failure is not — the target is invalid, so waiting will not help. After the last retry the event goes to the dead-letter list rather than being dropped silently.

What is stored on a delivery attempt

Each attempt records the status, the error type and a snippet of the response body, so you can see why a delivery failed without instrumenting your own endpoint.

Credential-bearing response headers are stored as [redacted]: authorization, proxy-authorization, set-cookie, set-cookie2, www-authenticate, proxy-authenticate and x-amz-security-token. If your endpoint echoes a token in one of these headers, it does not end up in the delivery log.