Custom ingest domain

Why use a custom domain?

Some providers restrict webhook targets to your own domain, some security reviews require it, and it keeps your ingest URL stable if you ever move platforms. It also stops the vendor name appearing in a partner’s configuration screen.

What do I need?

A hostname you control, usually a subdomain such as hooks.yourapp.com, and access to its DNS.

How do I set it up?

Three DNS records in total, added at three different points. Nothing is built for a hostname until you have proved you control it, so the order matters.

1. Add the hostname in Settings, Domains. Nothing is provisioned yet: you get back a TXT record and the domain sits as claimed.
2. Publish the TXT record we show you. This proves the hostname is yours. Without it anybody could ask us for a certificate covering a name they do not own.
3. Press Check. We look for the TXT record. DNS usually takes a few minutes to publish, so if it is not visible yet, wait and press it again.
4. Publish the CNAME the certificate authority asks for. Once ownership is proved we request a certificate, and the authority returns a validation record of its own. This is a different record from the one in step 2.
5. Press Check again once that record resolves. When the certificate is issued we attach the hostname and the domain becomes active.
6. Publish the final CNAME, pointing your hostname at the target shown against the active domain, then attach the domain to an endpoint.
7. Update the provider to the new URL, and confirm traffic is arriving before removing the old one.

Your endpoint path stays the same, so the full URL becomes https://hooks.yourapp.com/e/ep_7f3a91.

Why does it say the TXT record does not carry the right value?

Because a TXT record exists at that name but holds something else. The usual causes are a record from a previous attempt that was never removed, a value that was truncated when it was pasted, or quoting added by the DNS provider.

That message is deliberately different from “not visible yet”. The first means keep waiting; the second means fix the record, because waiting will never help.

Can I use my apex domain?

No, and the form will refuse it. A hostname pointed at us needs a CNAME, and a CNAME at the apex of a domain conflicts with the MX and NS records that live there. On most providers that breaks mail delivery for the whole domain.

Use a subdomain such as hooks.yourapp.com.

Can several endpoints share one domain?

Yes. The hostname is a front door and the path selects the endpoint, so one verified domain serves every endpoint on the account.

What happens if the certificate cannot renew?

We alert you before expiry and keep retrying. The usual cause is a CNAME that was removed or repointed. The shared ShellOrbit URL for the endpoint keeps working throughout, so you always have a fallback target.