The Webhook Endpoints API lets you manage where Everee sends your company's webhook events: add, change and remove endpoints, switch one off, rotate its signing key, and send a test event. A company can have up to three endpoints, and every event is sent to each of them.
| Endpoint | What it does |
|---|---|
| List webhook endpoints | Lists your endpoints |
| Get a webhook endpoint | Returns one endpoint |
| Create a webhook endpoint | Adds an endpoint and returns its signing key |
| Update a webhook endpoint | Changes its name, URL, or whether it is enabled |
| Delete a webhook endpoint | Removes an endpoint |
| Rotate a signing key | Issues a new signing key |
| Send a test event | Sends a test event to an endpoint |
You authenticate the same way as every other company endpoint: your company API key and tenant ID. See Authentication & API tokens. In embedded payroll, use the company's own API key, which is returned when you create the company and can be managed with the Company API keys endpoints. The key works as soon as the company is created, so you can set up an endpoint before onboarding finishes.
Hosted customers can also manage endpoints in the Everee admin portal, under Settings > Integrations Hub. Both manage the same endpoints.
An endpoint
| Field | Meaning |
|---|---|
id | The endpoint's ID, used in every other path |
name | A label for the endpoint |
url | The https URL events are sent to |
enabled | Whether Everee sends events to this endpoint |
signingKey | The key for verifying events. Shown in full only when you create the endpoint or rotate its key, and masked otherwise |
previousSigningKeyExpiresAt | After a rotation, until when the replaced key still signs events |
createdAt | When the endpoint was created |
URL rules
- The URL must be
https. - The host must be a public internet host. Private or internal addresses,
localhost, embedded credentials and fragments are rejected. - Two of your endpoints can't share a URL.
The signing key
Everee generates a signing key for each endpoint. It is shown in full once: in the response that creates the endpoint, and in the response that rotates its key. Every other response shows it masked, as **** followed by its last four characters, which is enough to tell your endpoints' keys apart. Store the full key like any credential, and keep one set per environment. See Sandbox & Production.
If you lose a key, or think it has leaked, rotate it. Both the new and the old key sign events for 24 hours, so you can switch your handler without missing an event. If you rotate again before the 24 hours are up, the oldest key stops signing at once.
Switching an endpoint off
Set enabled to false with Update a webhook endpoint to stop Everee sending events to that endpoint, and back to true to resume. To remove an endpoint for good, delete it, which also frees one of your three places.
Setting up an endpoint
- Create the endpoint and store the
signingKeyfrom the response. - Build your handler to verify the signature and follow the security advice.
- Send a test event and check that your handler accepts it.