​

Troubleshooting: webhook endpoint cap and DNS pre-create gates

​

Cause class: deterministic vs transient

​

WEBHOOK_ENDPOINT_CAP_REACHED — your tenant is at 10 endpoints

{
  "error": {
    "code": "WEBHOOK_ENDPOINT_CAP_REACHED",
    "status": 422,
    "details": { "limit": 10, "current": 10 }
  }
}

​

Fix option 1: delete an unused endpoint

1. List your endpoints — either Developer → Webhooks in the dashboard or the API:

curl "https://api.orbit.devotel.io/api/v1/webhooks" \
  -H "X-API-Key: dv_live_sk_..."

2. Pick the endpoint that no longer receives traffic — a retired integration, a staging URL, a duplicate pointing at the same handler.
3. Delete it:

curl -X DELETE "https://api.orbit.devotel.io/api/v1/webhooks/{id}" \
  -H "X-API-Key: dv_live_sk_..."

4. Re-submit the create call. It succeeds as soon as the count drops below 10.

​

Fix option 2: request a quota lift from support

• Your tenant id (Dashboard → Settings → Organization).
• The integrations each existing endpoint serves — one per integration is the expected pattern.
• The request_id from the 422 response’s error.meta block — quote the rejection envelope so support can pull the exact refused call.

​

What not to do

• Do not retry the same create call. The rejection is deterministic; the count does not change by itself.
• Do not delete and recreate in a loop to rotate endpoint ids. Endpoint ids are stable for a reason — signature verification and the DLQ key off them.
• Do not work around the cap by stacking multiple event streams on one endpoint’s URL path. One endpoint can subscribe to all event types; use the events array on the endpoints you already have.

​

WEBHOOK_DNS_INVALID — the hostname does not resolve

{
  "error": {
    "code": "WEBHOOK_DNS_INVALID",
    "status": 422,
    "details": { "url": "https://hooks.exmaple.io/inbound", "failure_code": "dns_invalid" }
  }
}

​

Recovery ladder

1. Resolve the hostname yourself. From any shell, check what public resolvers see:

nslookup hooks.exmaple.io
dig +short hooks.exmaple.io

2. Fix the typo. The most common cause is a mangled hostname — a swapped TLD (.com where your domain is .io), a dropped character, or a transposed pair. Compare the URL string in your create call against the record in your registrar character by character.
3. Confirm the record in your registrar or DNS provider. If the hostname is spelled right, the record itself may be missing: no A or AAAA for the host, or the zone moved providers and this record was not recreated. Add or repair the record at your DNS provider.
4. Wait out propagation if you just created the record. New records are visible once your provider’s TTL expires. Retry the create call after dig +short returns the address.
5. Re-create the endpoint. Only re-submit POST /api/v1/webhooks once step 1 succeeds from your shell — at that point Orbit’s resolver sees the same answer.

​

Pre-create DNS failure vs delivery-time DNS failure

​

What not to do

• Do not retry the create call against a hostname your own resolver cannot answer. The gate is deterministic — it fails the same way until public DNS answers.
• Do not bypass the gate with a raw IP address. Literal IPs from private ranges are rejected under INVALID_WEBHOOK_URL, and public IPs without a hostname still fail HTTPS certificate checks downstream. Give the receiver a real hostname.
• Do not treat NXDOMAIN as a reason to escalate. Check the spelling and the registrar first; escalate only when dig returns an address but Orbit still rejects with WEBHOOK_DNS_INVALID — quote the request_id from the response in that case.

​

Escalate when the fix is not in your hands

​

See also

• Troubleshooting: webhook endpoint creation errors — the sibling create-time gate (INVALID_WEBHOOK_URL — scheme and private-range rejections).
• Troubleshooting: failed webhook deliveries — retries, backoff, and the dead-letter queue after creation succeeds.
• Troubleshooting: webhook signature invalid — receiver-side verification failures after delivery.
• Error codes reference — the raw code table this page expands on.