Skip to main content

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 publishing a short file on it, and Entrupy checks that the file is there. You only need to do this once per domain.

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 that the token is not configured for webhooks.

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.

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",
  "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.

Step 2: Publish the file​

Make the url from the response return register_token as its content.

The address must:

  • be reachable from the public internet over HTTPS,
  • return the token directly, with no redirect to another address,
  • return only the token, with no extra text around it.

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.

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",
  "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 file, 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.

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.

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 the three steps 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.