Housecall Pro webhooks
Webhooks exist, and they are not a self-serve feature. There is no route to list your subscriptions, and an ordinary MAX-plan API key cannot create one. This page describes what is actually there, and the delivery behaviour that catches people who do get access.
The state of it
A webhook lets Housecall Pro push an event to you the moment it happens, instead of you asking repeatedly whether anything changed. That is the right architecture for anything that needs to react promptly.
On the public API, the surface is thin:
- No list route. There is no way to ask what subscriptions exist. Whatever you have configured, you cannot enumerate it through the API.
- Creating a subscription is partner-gated. The route is real. It answers with an error about a missing organisation app rather than a 404, but it wants a registered partner application, which an API key is not.
- So the practical route is through Housecall Pro, via their partner or developer contact, not something you configure yourself.
The distinction between a JSON error naming a missing app and an HTML 404 matters here: it tells you the path is correct and the credential is the problem, so you are asking Housecall Pro for access instead of hunting for the right URL. More on reading those responses in the API guide.
The delivery behaviour that bites
This is the part worth knowing before you build a receiver, because the failure is silent from your side.
A failing receiver gets switched off, quietly
Delivery is disabled aggressively when your endpoint returns errors. A receiver that throws a 5xx, during a deploy, a database restart or a bad migration, can have its subscription turned off. Nothing tells you. Events simply stop arriving, and the first symptom is downstream data that has quietly been frozen for a week.
Which gives three rules that are cheap to follow and expensive to skip:
- Return 2xx immediately, then work. Acknowledge on receipt, queue the payload, process it separately. Never let your business logic decide the HTTP status.
- Monitor for absence, not for errors. The failure mode is silence, so alert on "no events in longer than normal". An error-rate dashboard shows nothing at all when the feed is off.
- Reconcile periodically against the API. Treat webhooks as the fast path and a scheduled comparison as the truth. Anything that only ever learned about the world through events will silently diverge the first time one is missed.
Polling instead
For a lot of home service companies, polling is the more reliable answer and needs nobody's permission. The
catch is that you cannot ask only for what changed: updated_after is accepted and
then ignored, returning the full set. You page and compare client-side.
That costs requests, and the rate limit is sustained-volume rather than burst, so a long sweep draws 429s where a short one does not, so pace it and retry. The measured numbers are here.
Common questions
Does Housecall Pro support webhooks?
Yes, but not as a self-serve feature. There is no route to list your subscriptions, and creating one with an ordinary MAX-plan API key fails because the request expects a registered partner application. In practice, getting webhooks means going through Housecall Pro, not configuring them yourself with a key.
Why does POST to the Housecall Pro webhook subscription route fail?
Because a plain MAX API key is not a registered partner app. The route is real and returns an error naming the missing organisation app rather than a 404, which is the tell that the path exists and the credential is the problem, not the URL.
What happens if my Housecall Pro webhook receiver returns an error?
Delivery is disabled aggressively. A receiver that returns a 5xx can have its subscription switched off, and the failure is silent from your side: events simply stop. Always return a 2xx immediately on receipt and do the real work afterwards, and monitor for the absence of events rather than waiting to notice.
Can I poll the Housecall Pro API instead of using webhooks?
Yes, and for many home service companies it is the more reliable answer. The catch is that the updated_after filter is accepted and then ignored, so you cannot ask only for what changed. You page through and compare client-side. It costs more requests, and the rate limit is sustained-volume, so pace it.
Running the receiver is the hard part
A receiver has to be up at three in the morning, return 2xx under all circumstances, and notice when it stops being fed. A 5xx can switch the subscription off, so an endpoint that goes down quietly stops receiving and does not announce it. That is a service to operate, not a file to install, and the page above is written so it can be built and operated in-house.
Questions about a specific setup go to hello@hcpapi.com.