HospetKnowledge DeskLog In

Using the Hospet Connect API and Webhooks

Last updated on

The Hospet Connect API connects your practice management software to Hospet. Your software can work with your practice’s information in Hospet, and webhooks tell it when something happens, so it doesn’t have to keep checking. We’re adding to what the API can do over time.

This article covers the setup your practice does in Hospet Connect. Your developer or software vendor can find the technical details in the API reference.

🔑 Who Can Set This Up

The API & Webhooks page is available to admins of an approved Hospet Connect account. To open it, click your profile picture at the top right of any page and choose API & Webhooks.

The Developers link at the bottom of every page opens the technical API reference for your developer.

🗝️ Creating an API Key

Your software uses an API key to connect to Hospet.

  1. Click your profile picture at the top right and choose API & Webhooks.
  2. Click “Create API Key” and give it a name you’ll recognize, like the name of your practice software.
  3. Copy the key and give it to your developer or software vendor.

The key is only shown once. Store it somewhere safe, such as a password manager. If it’s lost, create a new key and revoke the old one.

Anyone with the key can use the API in your practice’s name, so treat it like a password. You can have up to 10 active keys, for example one for each system that connects to Hospet.

Assessments your software sends are sent on behalf of the person who created the key. When your client submits one, the results email goes to that person and to your practice’s primary contact email. If that person is no longer on your account, it goes to the account owner instead.

If your software opens pets in Hospet Connect for you (see Opening Pets From Your Practice Software), it signs in as this same person. Because of this, anyone who has the key can get into Hospet Connect as them.

🚫 Revoking an API Key

If a key may have been seen by someone who shouldn’t have it, or you stop using the software, click “Revoke” next to the key on the API & Webhooks page, then confirm. Any software using that key stops working immediately.

📬 Adding a Webhook Endpoint

A webhook endpoint is the address in your practice software where Hospet sends updates, such as assessment results. Your developer or software vendor will give you the URL.

  1. Click your profile picture at the top right and choose API & Webhooks.

  2. Click “Add Endpoint” and enter the URL. It must start with https://. You can also add a description.

  3. Choose which events to send it:

    • a client completing a one-time assessment
    • a client saving a completed one-time assessment to their Hospet account
    • a client adding your practice to their support team
    • a client sharing a pet with your practice, or no longer sharing one
    • a client removing your practice from their support team

    When Hospet adds more, existing endpoints don’t receive them until you turn them on in the endpoint’s settings.

  4. Save the endpoint. On its page, click “Reveal” to see the signing secret, which starts with whsec_, and give it to your developer. Their software uses it to check that results really came from Hospet.

You can add up to 5 endpoints.

If the signing secret may have been exposed, click “Roll Secret” on the endpoint’s page to replace it. The old secret stops working straight away, so give your developer the new one at the same time.

📄 What Gets Sent

When a client submits a one-time assessment, Hospet sends each of your endpoints:

  • Your client’s and their pet’s details
  • The score for each category
  • Any reference your software attached, such as a patient ID
  • The full assessment as a PDF

This happens for every one-time assessment your practice sends, whether it came from your software or from the One-Time Assessments page.

When a client saves a completed one-time assessment to their Hospet account, Hospet sends the endpoints that have that event turned on the same assessment details, plus which Hospet client and pet it was saved to. Your software can use this to link the patient in your records to the pet in Hospet, using the reference it attached.

When a client adds your practice to their support team, changes which pets they share with you, or removes your practice, Hospet sends the endpoints that have those events turned on:

  • Your client’s name and email
  • The name, species and breed of each pet they share with your practice. When they remove your practice, no pets are sent.

Pets your client hasn’t shared with your practice are never sent.

🧪 Testing the Connection

On an endpoint’s page, click “Send Test Event” to send a sample event, such as a sample result with a sample PDF. If the endpoint has more than one event turned on, choose which one to send first. It isn’t linked to a real client. Ask your developer to confirm it arrived.

The endpoint’s page also lists recent deliveries and whether each one worked. If one failed, click “Retry” to send it again once the problem is fixed.

If a delivery is waiting to be retried, click “Retry Now” to send it straight away instead of waiting. If it fails again, Hospet keeps retrying it on the usual schedule.

⚠️ If Deliveries Keep Failing

If your software can’t be reached, Hospet keeps trying for about 3 days. If the last try fails and the endpoint hasn’t accepted anything in that time, Hospet turns the endpoint off and emails your practice’s primary contact and account admins.

Once your developer has fixed the problem, click “Turn On” on the endpoint’s page. Events from while it was off aren’t sent again automatically. You can still see results on the One-Time Assessments page and clients in your Client List, and your software can fetch both through the API.

✉️ Emails to Your Client

Assessments sent through the API work just like ones sent from Hospet Connect: Hospet emails your client the link.

Your software can choose to skip that email and send the link itself, for example by text message. Only the invitation is skipped. When your client submits the assessment, Hospet still emails the results to them and to your practice.

🏷️ How API Assessments Appear in Hospet Connect

Assessments your software sends appear in your One-Time Assessments list alongside the others, marked via API.

If your software sent the link itself, the status shows Link created instead of Sent. Hospet never emailed these, so they can’t be resent from Hospet.

🔗 Opening Pets From Your Practice Software

Your software can add a button such as View in Hospet to a patient’s record. Clicking it opens that pet’s page in Hospet Connect, already signed in, so your team doesn’t need to know your practice’s Hospet login.

  • Who it signs in as: the person who created the API key, while they’re still on your account. Otherwise it’s the account owner. Everyone who uses the button is signed in as that person.
  • Two-factor authentication: if that person has two-factor authentication turned on, Hospet asks for their verification code before opening the pet.
  • Which pets: only pets your clients share with your practice.
  • Other people: if someone else was signed in to Hospet in that browser, they’re signed out first.

Each link works once, for 60 seconds. If you see This link has expired, go back to your practice software and click the button again.

🛠️ For Your Developer

Share these sections of the API reference with your developer or software vendor: