Registering a Webhook Domain
Entrupy only sends webhook notifications to domains that your organization has verified. Verification is self-serve: you prove you control the domain by making one address on it return a token that Entrupy gives you, and Entrupy checks that the token is there. You only need to do this once per domain.
You can verify a whole domain, or only a path on it. There are two ways to verify:
- Verify an endpoint URL. Entrupy sends a test request to your webhook URL and your receiver answers it. This is the easiest option when your webhook receiver is an application or serverless function on a shared platform, where you cannot serve files from the root of the host. It verifies only that URL's path.
- Verify with a token (steps 1 to 3 below). You serve a token at an address Entrupy gives you. Use this to verify a whole domain, or a path on it with
path_prefix.
All requests on this page use the v2 API, so send the header Api-Version: 2.0 and an API token that has webhooks enabled.
Your usual API token is issued through your Entrupy partner account. Webhooks are not on by default. Ask your Entrupy contact or developer@entrupy.com to enable webhooks on that token (or to issue a token that already has them). Use the same Authorization: Token … header as the rest of the API. If a request returns an error saying the token is not configured for webhooks, webhooks have not been enabled on that token yet; contact us as described above.
Step 1: Start verification
Tell Entrupy which domain you want to verify. Send the hostname on its own, with no https://, no path, and no trailing slash. To verify only a path on that domain, also send path_prefix (see Verifying only a path).
POST /v2/domains/start_registration HTTP/1.1
Host: api.entrupy.com
Api-Version: 2.0
Authorization: Token [valid_token]
Content-Type: application/json
{
"domain_name": "hooks.acme.com"
}
Example response:
{
"domain_name": "hooks.acme.com",
"path_prefix": null,
"url": "https://hooks.acme.com/entrupy_url_registration/abcdefghijklmnopqrstuvwxyz0123456789ABCDEFG",
"verifier": "abcdefghijklmnopqrstuvwxyz0123456789ABCDEFG",
"register_token": "abcdefghijklmnopqrstuvwxyz0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789abc",
"expires_at": "2026-09-18T15:04:05Z"
}
Keep verifier and register_token. Treat register_token like a password: share it only with the person setting up the web server, and do not post it publicly or write it to logs.
Verifying only a path
Send path_prefix when you control a path on the host but not its root. This is common on shared hosting, where many customers share one hostname and each gets their own path.
POST /v2/domains/start_registration HTTP/1.1
Host: api.entrupy.com
Api-Version: 2.0
Authorization: Token [valid_token]
Content-Type: application/json
{
"domain_name": "hooks.example.net",
"path_prefix": "/tenants/acme"
}
Example response:
{
"domain_name": "hooks.example.net",
"path_prefix": "/tenants/acme",
"url": "https://hooks.example.net/tenants/acme/entrupy_url_registration/abcdefghijklmnopqrstuvwxyz0123456789ABCDEFG",
"verifier": "abcdefghijklmnopqrstuvwxyz0123456789ABCDEFG",
"register_token": "abcdefghijklmnopqrstuvwxyz0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789abc",
"expires_at": "2026-09-18T15:04:05Z"
}
The token address in url is now under the prefix, so serve the token there in step 2. Send the same path_prefix again in step 3. Webhooks can then use only URLs under that path; see How webhook URLs are matched.
A path_prefix must:
- start with
/, - use only letters, digits,
/and these characters:- . _ ~ ! $ & ' ( ) * + , = : @, - not contain percent-encoding (
%), empty segments (//), or.or..segments, - be at most 512 characters long.
A trailing / is dropped, so /tenants/acme/ is the same as /tenants/acme. A path_prefix of / on its own verifies the whole domain, the same as leaving it out.
Step 2: Serve the token
Make the url from the response return register_token as its content. The url is on the hostname you sent in step 1, so set this up on whatever server answers for that hostname. For example, verifying hooks.acme.com does not require any change to acme.com.
You can serve the token in either of two ways:
- As a file. Upload a file containing the token to your web server or file host so that it is available at the path in
url. - From a web service. Add a route to the application that receives your webhooks, for example
/entrupy_url_registration/{verifier}, that responds with the token. No file needs to exist on disk.
Either way, the address must:
- be reachable from the public internet over HTTPS, without a login or API key,
- return the token directly, with no redirect to another address,
- return only the token, with no extra text around it (for example, no JSON wrapper or quotation marks).
Verification links expire. Finish step 3 before the expires_at time in the response, or start again to get a new link.
Step 3: Finish verification
Send back the same domain and the verifier from step 1. If you sent a path_prefix in step 1, send the same one here.
POST /v2/domains/finish_registration HTTP/1.1
Host: api.entrupy.com
Api-Version: 2.0
Authorization: Token [valid_token]
Content-Type: application/json
{
"domain_name": "hooks.acme.com",
"verifier": "abcdefghijklmnopqrstuvwxyz0123456789ABCDEFG"
}
Example response:
{
"create_time": {
"display": "2017-05-15T14:06:58+00:00",
"epoch": 1494857218.0
},
"domain_name": "hooks.acme.com",
"domain_owner": {
"organization": {"name": "Example Reseller"},
"user": {"username": "authenticator@example.com"}
},
"domain_uuid": "b9b39947-8a16-483d-a7eb-2b961c41b2f7",
"path_prefix": null,
"verifier": "abcdefghijklmnopqrstuvwxyz0123456789ABCDEFG"
}
The domain is now verified, and you can create webhooks that point to it. Save the domain_uuid if you may want to remove the domain later; you can also look it up at any time with the list below.
If Entrupy cannot read the token, the response explains that the check failed. Confirm the address opens in a browser and returns the token, then try again. Too many failed attempts in a row are temporarily blocked, so wait a moment before retrying.
Calling finish again for a domain that is already verified is safe and simply returns the same domain.
Verifying an endpoint URL
Instead of serving a token, you can ask Entrupy to check your webhook URL directly. Your receiver answers a one-time challenge, and Entrupy verifies the host and the URL's path in one request. Use this when your webhook receiver is an application or serverless function, for example on a shared hosting platform.
POST /v2/domains/verify_endpoint HTTP/1.1
Host: api.entrupy.com
Api-Version: 2.0
Authorization: Token [valid_token]
Content-Type: application/json
{
"url": "https://api.example.com/hooks/abc"
}
The url must use https:// and must not have a query string (?…) or fragment (#…).
While handling this request, Entrupy sends a POST to that URL:
POST /hooks/abc HTTP/1.1
Host: api.example.com
Content-Type: application/json
{
"type": "url_verification",
"challenge": "3eZbrw1aBm2rZgRNFdxV2595E9CY3gmdALWMmHkvFXO7tYXAYM8P"
}
Your receiver must reply within 5 seconds with HTTP 200, without a redirect. The body must be one of:
- the
challengevalue on its own, for example3eZbrw1aBm2rZgRNFdxV2595E9CY3gmdALWMmHkvFXO7tYXAYM8P, or - the JSON object
{"challenge": "3eZbrw1aBm2rZgRNFdxV2595E9CY3gmdALWMmHkvFXO7tYXAYM8P"}, with no other keys.
A minimal receiver in Python with Flask:
import flask
app = flask.Flask(__name__)
@app.post("/hooks/abc")
def entrupy_webhook():
body = flask.request.get_json(silent=True) or {}
if body.get("type") == "url_verification":
return flask.jsonify(challenge=body["challenge"])
# Verify the Entrupy-Signature header and handle the event here.
return flask.jsonify(status="ok")
Check for url_verification before you check the Entrupy-Signature header. You verify the URL before you create a webhook for it, so the challenge cannot be signed with a webhook secret.
If your receiver answers correctly, the host and the URL's path are verified, and the response is the domain:
{
"create_time": {
"display": "2017-05-15T14:06:58+00:00",
"epoch": 1494857218.0
},
"domain_name": "api.example.com",
"domain_owner": {
"organization": {"name": "Example Reseller"},
"user": {"username": "authenticator@example.com"}
},
"domain_uuid": "0c5d2f1e-6a47-4f0b-9d1e-3b8a7c2e4f60",
"path_prefix": "/hooks/abc"
}
You can now create webhooks that point to https://api.example.com/hooks/abc, or to any URL under that path.
If your receiver does not answer in time, answers with another status code or a redirect, or returns a different body, the response is a 400 error saying verification failed. Fix the receiver and try again. As with finishing verification, too many failed attempts in a row are temporarily blocked.
How webhook URLs are matched
When you create a webhook, its URL must be on a domain your organization has verified:
- A domain verified without a
path_prefixcovers every URL on that host. - A domain verified with a
path_prefixcovers URLs on that host whose path is the prefix itself, or continues it after a/. For example,/tenants/acmecovers/tenants/acmeand/tenants/acme/orders, but not/tenants/acmecorp. - If more than one verification matches a URL, the one with the longest (most specific)
path_prefixis used. - A domain verified with a
path_prefixcovers only the default HTTPS port. A webhook URL with any other port, such ashttps://hooks.acme.com:8443/tenants/acme, needs the whole domain verified.
Listing your domains
POST /v2/search/domains HTTP/1.1
Host: api.entrupy.com
Api-Version: 2.0
Authorization: Token [valid_token]
Content-Type: application/json
{}
This returns the domains your organization has verified and can use right now. Domains you have removed are not included. Each domain includes path_prefix: null if the whole domain is verified, or the path it is limited to.
Removing a domain
Removing a domain stops it from being used for new webhooks.
POST /v2/domains/b9b39947-8a16-483d-a7eb-2b961c41b2f7/deactivate HTTP/1.1
Host: api.entrupy.com
Api-Version: 2.0
Authorization: Token [valid_token]
Content-Type: application/json
{}
Example response:
{
"status": "ok"
}
A few things to expect:
- Turn off the webhooks first. While any active webhook still sends notifications to that domain, the request is refused and the domain stays in place. Deactivate those webhooks, then remove the domain. Removing a domain never deletes webhooks for you.
- Removing a domain is not reversible. If you need the domain again later, verify it again with one of the methods above.
- Unknown or already-removed domains return an error saying the domain is not registered.
See the API Reference v2 for the full request and response details.