Webhook JSON Schemas
Machine-readable definitions of the webhook envelopes and the announcement event.
These JSON Schemas (draft 2020-12) define what Everee sends, so you can validate requests in your handler or generate types from them. Validate the body only after you have verified the signature.
A request is a company event or a partner event, told apart by the x-everee-webhook-audience header (company or partner) or by which of companyId and partnerId is present. See the Webhooks Overview.
Company envelope
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://developer.everee.com/schemas/webhook-company-envelope.json",
"title": "Company webhook envelope",
"description": "What Everee sends to a company's webhook endpoint. A company's events always carry companyId and never partnerId.",
"type": "object",
"required": ["version", "id", "companyId", "type", "timestamp", "data"],
"not": { "required": ["partnerId"] },
"properties": {
"version": { "const": "1" },
"id": { "type": "string", "minLength": 1 },
"companyId": { "type": "integer" },
"type": { "type": "string", "minLength": 1 },
"timestamp": { "type": "integer" },
"data": {
"type": "object",
"required": ["object"],
"properties": { "object": { "type": "object" } }
}
}
}Partner envelope
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://developer.everee.com/schemas/webhook-partner-envelope.json",
"title": "Partner webhook envelope",
"description": "What Everee sends to a partner's webhook endpoint. A partner's events always carry partnerId and never companyId.",
"type": "object",
"required": ["version", "id", "partnerId", "type", "timestamp", "data"],
"not": { "required": ["companyId"] },
"properties": {
"version": { "const": "1" },
"id": { "type": "string", "minLength": 1 },
"partnerId": { "type": "integer" },
"type": { "type": "string", "minLength": 1 },
"timestamp": { "type": "integer" },
"data": {
"type": "object",
"required": ["object"],
"properties": { "object": { "type": "object" } }
}
}
}Announcement event object
The data.object of announcement.published, announcement.updated and announcement.retracted. See Announcement events.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://developer.everee.com/schemas/announcement-event-object.json",
"title": "Announcement event data.object",
"description": "The data.object of announcement.published, announcement.updated and announcement.retracted. Fields without a value are omitted. retractedAt appears only on announcement.retracted. The full text is not included: read it with the Announcements API. Ignore fields and details keys you don't know.",
"type": "object",
"required": ["id", "kind", "category", "severity", "reader", "title", "summary", "scope", "actionRequired", "details", "publishedAt"],
"properties": {
"id": { "type": "integer" },
"key": { "type": "string" },
"kind": { "enum": ["INTEGRATION", "PRODUCT", "OPERATIONS"] },
"category": {
"enum": [
"API_RELEASE", "DEPRECATION", "MAINTENANCE", "SECURITY",
"FEATURE", "DOCUMENTATION", "OFFERING",
"SERVICE_DISRUPTION", "YEAR_END", "BANK_HOLIDAY", "COMPLIANCE_CHANGE"
]
},
"severity": { "enum": ["INFO", "IMPORTANT", "CRITICAL"] },
"reader": { "enum": ["PARTNER", "CUSTOMER"] },
"title": { "type": "string" },
"summary": { "type": "string" },
"scope": {
"type": "object",
"description": "Which companies it applies to. Treat a type you don't know as 'may apply'.",
"required": ["type"],
"properties": {
"type": { "type": "string", "description": "ALL or STATES." },
"states": {
"type": "array",
"description": "With type STATES: two-letter state codes.",
"items": { "type": "string", "pattern": "^[A-Z]{2}$" }
}
}
},
"startsAt": { "type": "string", "format": "date-time" },
"endsAt": { "type": "string", "format": "date-time" },
"displayUntil": { "type": "string", "format": "date-time" },
"actionRequired": { "type": "boolean" },
"actionBy": { "type": "string", "format": "date" },
"details": {
"type": "object",
"description": "Fields specific to the category; {} when it has none. DEPRECATION: sunsetDate, endpoints, replacement. MAINTENANCE: affects. SERVICE_DISRUPTION: status, affects. BANK_HOLIDAY: date, name. COMPLIANCE_CHANGE: changeKey, domain, rule, state, effectiveDate, from, to.",
"properties": {
"sunsetDate": { "type": "string", "format": "date" },
"endpoints": { "type": "array", "items": { "type": "string" } },
"replacement": { "type": "string" },
"affects": {
"type": "array",
"items": { "enum": ["API", "EMBEDDED_EXPERIENCES", "WEBHOOKS", "PAYROLL_RUNS", "FUNDING", "PAYOUTS", "TAX_FILING", "REPORTS"] }
},
"status": { "enum": ["INVESTIGATING", "IDENTIFIED", "MONITORING", "RESOLVED"] },
"date": { "type": "string", "format": "date" },
"name": { "type": "string" },
"changeKey": { "type": "string" },
"domain": { "type": "string", "description": "TAX, MINIMUM_WAGE, LEAVE, OVERTIME, PAY_FREQUENCY or OTHER. Treat a value you don't know as OTHER." },
"rule": { "type": "string" },
"state": { "type": "string", "pattern": "^[A-Z]{2}$" },
"effectiveDate": { "type": "string", "format": "date" },
"from": { "type": "string", "description": "A decimal string." },
"to": { "type": "string", "description": "A decimal string." }
}
},
"affected": { "type": "string" },
"learnMoreUrl": { "type": "string" },
"publishedAt": { "type": "string", "format": "date-time" },
"retractedAt": { "type": "string", "format": "date-time" }
}
}These schemas describe the shape of a request and are not exhaustive for every event type: data.object is validated as an object here, and each event's own structure is on its documentation page. Everee may add fields to an object over time, so don't reject a request only because it has a field you don't know. The schemas allow extra fields.
Updated 13 days ago