Webhooks Overview

Everee sends webhook events to tell your system that something happened, so you don't have to poll. Every event is an HTTPS POST to an endpoint you register, with a JSON body and a signature you can verify.

Events go to one of two audiences, and each audience has its own endpoints, its own API key, its own envelope and its own documentation.

	Company webhooks	Partner webhooks
Who receives them	A company, at that company's endpoints	A partner that builds Everee into its product, at the partner's own endpoints
What they are about	One company: its workers, payments, reports, onboarding	The partner as a whole, such as announcements
Envelope identifies the owner with	`companyId` (never `partnerId`)	`partnerId` (never `companyId`)
Header `x-everee-webhook-audience`	`company`	`partner`
Endpoints	Up to 3 per company	Up to 3 per partner
Manage endpoints with	The Webhook Endpoints API and the company API key, or the admin portal	The Partner Webhook Endpoints API and the partner API key
Signing keys	One per company endpoint	One per partner endpoint
Events	Company Webhook Events, Company Onboarding Events	Partner Webhook Events

Announcement events are sent to both audiences: a company that uses Everee directly receives them as company webhooks, and a partner that builds Everee into its product receives them as partner webhooks.

Which do I need?

You use Everee for your own company (a hosted customer, or an integration for one company): you need company webhooks. Start with Company Webhook Events.
You are a partner that creates and manages companies on Everee: your companies' events go to each company's endpoints, as above, and you can set those up when you create the company. To also receive events about your partnership as a whole, register partner endpoints. Start with Partner Webhooks.

The two envelopes

Both use the same version, id, type, timestamp and data fields. They differ only in the owner field.

{
  "version": "1",
  "id": "abcdef-...",
  "companyId": 10011,
  "type": "worker.created",
  "timestamp": 17200110020,
  "data": { "object": { } }
}

{
  "version": "1",
  "id": "abcdef-...",
  "partnerId": 4821,
  "type": "announcement.published",
  "timestamp": 17200110020,
  "data": { "object": { } }
}

Don't assume companyId exists on every request. A handler that serves both audiences should read the x-everee-webhook-audience header first, then parse the body. Both envelopes are defined as JSON Schemas.

What every webhook shares

Topic	What to know	Read
Signature	Every request is signed with HMAC-SHA256 using the signing key of the endpoint that received it. The audience header is not part of the signed message	Authenticating Events
Replay and timing protection	Check the timestamp and compare signatures in constant time	Securing a Webhook Handler
Responding and retries	Return a 2xx quickly. Everee retries a failed delivery up to 20 times over about 6.6 days	Implementing a Webhook Handler
Duplicates	The same event can arrive more than once. Use the envelope's `id` to skip repeats	Implementing a Webhook Handler
Signing key rotation	A rotated key and the key it replaced both sign for 24 hours	The endpoints API guide for your audience
Sandbox and Production	Each environment has its own endpoints and keys	Sandbox & Production

Where to go next

Company Webhook Events: the catalog of company events and payloads.
Company Onboarding Events and Returned Deposits and Retries.
Partner Webhooks and Partner Webhook Events.
Announcement Events: the events both audiences receive.
Webhook JSON Schemas: machine-readable definitions of the envelopes and the announcement event.