> ## Documentation Index
> Fetch the complete documentation index at: https://developers.techwolf.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Event Types
All webhook payloads follow the
[CloudEvents 1.0](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md)
specification. Each event has a **type** (e.g.
`ai.techwolf.employee.skill_profile.updated.v1`) and a **data** object with
tenant and resource identifiers. You only need to support the event types you
consume; the **health check** event is required for all consumers.
## Event type reference
Events are grouped by entity. Follow the links to the full specification and
example payload for each type.
**Employee**
* [Skill Profile Updated](#employee-skill-profile-updated) - Employee Skills
added/removed or attributes updated
* [Suggested Skill Profile Updated](#employee-suggested-skill-profile-updated) -
Employee suggested (inferred, not yet validated) Skills changed
**Job**
* [Skill Profile Updated](#job-skill-profile-updated) - Job Skills added/removed
or attributes updated
* [Suggested Skill Profile Updated](#job-suggested-skill-profile-updated) - Job
suggested (inferred, not yet validated) Skills changed
**Course**
* [Skill Profile Updated](#course-skill-profile-updated) - Course Skills
added/removed
**Taxonomy (Skills)**
* [Skill Created](#skill-created) - New Skill in vocabulary or Custom Skill
created
* [Skill Updated](#skill-updated) - Skill or Custom Skill updated
* [Skill Deleted](#skill-deleted) - Skill removed from vocabulary or Custom
Skill deleted
* [Taxonomy Updated](#taxonomy-updated) - The tenant Taxonomy or Vocabulary
changes
**Health Check** (required for all endpoints)
* [Health Check](#health-check) - Liveness check
## Event specifications
Below are the full specifications for each event type, grouped by entity: when
it is emitted, expected frequency, suggested consumer action, and payload
format. The expected frequency is expressed per affected entity (e.g. per
Employee, per Job); this is not the total number of webhooks per day. Note that
this is only a high-level indication; actual frequency is dependent on the
activity levels in the SkillEngine API or any linked system such as the TechWolf
Skill Assistant, the TechWolf Console, external platforms with integrations,
etc. As for when the events are emitted, we offer at-least-once delivery on at
least the triggers specified per event.
TechWolf may add new fields to existing webhook versions (e.g. extra fields in
the `data` object). Your endpoint should tolerate unknown fields and not break
when new ones are sent.
***
### Employee Skill Profile Updated
| Detail | Specification |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Emitted when** | Inference completes for the Employee (including the initial inference after the Employee is created, which may produce an empty Skill Profile), Skills are validated or rejected, or the Skill attributes (e.g. proficiency) of existing validated Skills are updated. |
| **Expected frequency** | Daily (per Employee) |
| **Suggested action** | Retrieve the Employee Skill Profile from the SkillEngine API ([GET /employees/\{external\_id}/skill\_profile](/reference/latest/Employees/EmployeeProfile/get-employees-external-id-skill-profile)) and propagate changes. |
An empty Skill Profile (`"skills": []`) is a valid state: it means inference
has run for the Employee but no Skills could be inferred (yet). Treat these
webhooks like any other — fetch the Skill Profile by `external_id` without
special-casing. As soon as Skills are inferred or validated, they will flow
through on a subsequent webhook.
**Event type:** `ai.techwolf.employee.skill_profile.updated.v1`
**Event data**
| Field | Description |
| ------------- | ------------------------------------------------------------- |
| `tenant_name` | Identifies the tenant. |
| `external_id` | Employee's external ID; use in the path when calling the API. |
```json theme={null}
{
"specversion": "1.0",
"type": "ai.techwolf.employee.skill_profile.updated.v1",
"source": "https://{tenant}.{region}.techwolf.ai/employees/{employee_external_id}/skill_profile",
"id": "{event_uuid}",
"time": "2024-01-15T10:30:00Z",
"data": {
"tenant_name": "{tenant}",
"external_id": "{employee_external_id}"
}
}
```
***
### Employee Suggested Skill Profile Updated
| Detail | Specification |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Emitted when** | The set of suggested (inferred, not yet validated or rejected) Skills for the Employee changes. |
| **Suggested action** | Retrieve the Employee Skill Profile from the SkillEngine API ([GET /employees/\{external\_id}/skill\_profile](/reference/latest/Employees/EmployeeProfile/get-employees-external-id-skill-profile)) and read the Skills with `validation_state` `suggested`. |
This event covers **suggested** Skills only (inferred, not yet validated or
rejected). It is separate from [Employee Skill Profile
Updated](#employee-skill-profile-updated), which covers validated Skill
Profile changes. Subscribe to it on a webhook to be notified when the
suggested Skills change.
**Event type:** `ai.techwolf.employee.skill_profile.suggested_updated.v1`
**Event data**
| Field | Description |
| ------------- | ------------------------------------------------------------- |
| `tenant_name` | Identifies the tenant. |
| `external_id` | Employee's external ID; use in the path when calling the API. |
```json theme={null}
{
"specversion": "1.0",
"type": "ai.techwolf.employee.skill_profile.suggested_updated.v1",
"source": "https://{tenant}.{region}.techwolf.ai/employees/{employee_external_id}/skill_profile",
"id": "{event_uuid}",
"time": "2024-01-15T10:30:00Z",
"data": {
"tenant_name": "{tenant}",
"external_id": "{employee_external_id}"
}
}
```
***
### Job Skill Profile Updated
| Detail | Specification |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Emitted when** | Inference completes for the Job (including the initial inference after the Job is created, which may produce an empty Skill Profile), Skills are validated or rejected, or the Skill attributes (e.g. proficiency, criticality) of existing validated Skills are updated. |
| **Expected frequency** | Weekly-monthly (per Job) |
| **Suggested action** | Retrieve the Job Skill Profile from the SkillEngine API ([GET /job\_architecture/jobs/\{job\_external\_id}/skill\_profile](/reference/latest/Jobs/JobProfile/get-job-architecture-jobs-job-external-id-skill-profile)) and propagate changes. |
An empty Skill Profile (`"skills": []`) is a valid state: it means inference
has run for the Job but no Skills could be inferred (yet). Treat these
webhooks like any other — fetch the Skill Profile by `external_id` without
special-casing. As soon as Skills are inferred or validated, they will flow
through on a subsequent webhook.
**Event type:** `ai.techwolf.job_architecture.job.skill_profile.updated.v1`
**Event data**
| Field | Description |
| ------------- | -------------------------------------------------------- |
| `tenant_name` | Identifies the tenant. |
| `external_id` | Job's external ID; use in the path when calling the API. |
```json theme={null}
{
"specversion": "1.0",
"type": "ai.techwolf.job_architecture.job.skill_profile.updated.v1",
"source": "https://{tenant}.{region}.techwolf.ai/job_architecture/jobs/{job_external_id}/skill_profile",
"id": "{event_uuid}",
"time": "2024-01-15T10:30:00Z",
"data": {
"tenant_name": "{tenant}",
"external_id": "{job_external_id}"
}
}
```
***
### Job Suggested Skill Profile Updated
| Detail | Specification |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Emitted when** | The set of suggested (inferred, not yet validated or rejected) Skills for the Job changes. |
| **Suggested action** | Retrieve the Job Skill Profile from the SkillEngine API ([GET /job\_architecture/jobs/\{job\_external\_id}/skill\_profile](/reference/latest/Jobs/JobProfile/get-job-architecture-jobs-job-external-id-skill-profile)) and read the Skills with `validation_state` `suggested`. |
This event covers **suggested** Skills only (inferred, not yet validated or
rejected). It is separate from [Job Skill Profile
Updated](#job-skill-profile-updated), which covers validated Skill Profile
changes. Subscribe to it on a webhook to be notified when the suggested
Skills change.
**Event type:**
`ai.techwolf.job_architecture.job.skill_profile.suggested_updated.v1`
**Event data**
| Field | Description |
| ------------- | -------------------------------------------------------- |
| `tenant_name` | Identifies the tenant. |
| `external_id` | Job's external ID; use in the path when calling the API. |
```json theme={null}
{
"specversion": "1.0",
"type": "ai.techwolf.job_architecture.job.skill_profile.suggested_updated.v1",
"source": "https://{tenant}.{region}.techwolf.ai/job_architecture/jobs/{job_external_id}/skill_profile",
"id": "{event_uuid}",
"time": "2024-01-15T10:30:00Z",
"data": {
"tenant_name": "{tenant}",
"external_id": "{job_external_id}"
}
}
```
***
### Course Skill Profile Updated
| Detail | Specification |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Emitted when** | Skills are added to or removed from the Course Skill Profile. |
| **Expected frequency** | Monthly (per Course) |
| **Suggested action** | Retrieve the Course Skill Profile from the SkillEngine API ([GET /courses/\{external\_id}/skill\_profile](/reference/latest/Courses/CourseProfile/get-courses-external-id-skill-profile)) and propagate changes. |
**Event type:** `ai.techwolf.course.skill_profile.updated.v1`
**Event data**
| Field | Description |
| ------------- | ----------------------------------------------------------- |
| `tenant_name` | Identifies the tenant. |
| `external_id` | Course's external ID; use in the path when calling the API. |
```json theme={null}
{
"specversion": "1.0",
"type": "ai.techwolf.course.skill_profile.updated.v1",
"source": "https://{tenant}.{region}.techwolf.ai/courses/{course_external_id}/skill_profile",
"id": "{event_uuid}",
"time": "2024-01-15T10:30:00Z",
"data": {
"tenant_name": "{tenant}",
"external_id": "{course_external_id}"
}
}
```
***
### Skill Created
| Detail | Specification |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Emitted when** | New Skills are added to the TechWolf vocabulary, or Custom Skills are created. |
| **Expected frequency** | Monthly-quarterly (per Skill) |
| **Suggested action** | Retrieve the new Skill from the SkillEngine API ([GET /taxonomy/skills/\{skill\_id}](/reference/latest/Taxonomy/TaxonomySkills/get-taxonomy-skills-skill-id)) and propagate changes. |
**Event type:** `ai.techwolf.taxonomy.skill.created.v1`
**Event data**
| Field | Description |
| ----------------- | ------------------------------------------------------------------------------------------------------ |
| `tenant_name` | Identifies the tenant. |
| `external_id` | Identifies the Skill. |
| `external_vendor` | Indicates the Skill's vendor; pass as the vendor query parameter when fetching the Skill from the API. |
```json theme={null}
{
"specversion": "1.0",
"type": "ai.techwolf.taxonomy.skill.created.v1",
"source": "https://{tenant}.{region}.techwolf.ai/taxonomy/skills/{skill_external_id}",
"id": "{event_uuid}",
"time": "2024-01-15T10:30:00Z",
"data": {
"tenant_name": "{tenant}",
"external_id": "{skill_external_id}",
"external_vendor": "{skill_external_vendor}"
}
}
```
***
### Skill Updated
| Detail | Specification |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Emitted when** | Skills are updated in the TechWolf vocabulary, or Custom Skills are updated. |
| **Expected frequency** | Monthly-quarterly (per Skill) |
| **Suggested action** | Retrieve the updated Skill from the SkillEngine API ([GET /taxonomy/skills/\{skill\_id}](/reference/latest/Taxonomy/TaxonomySkills/get-taxonomy-skills-skill-id)) and propagate changes. |
**Event type:** `ai.techwolf.taxonomy.skill.updated.v1`
**Event data**
| Field | Description |
| ----------------- | ------------------------------------------------------------------------------------------------------ |
| `tenant_name` | Identifies the tenant. |
| `external_id` | Identifies the Skill. |
| `external_vendor` | Indicates the Skill's vendor; pass as the vendor query parameter when fetching the Skill from the API. |
```json theme={null}
{
"specversion": "1.0",
"type": "ai.techwolf.taxonomy.skill.updated.v1",
"source": "https://{tenant}.{region}.techwolf.ai/taxonomy/skills/{skill_external_id}",
"id": "{event_uuid}",
"time": "2024-01-15T10:30:00Z",
"data": {
"tenant_name": "{tenant}",
"external_id": "{skill_external_id}",
"external_vendor": "{skill_external_vendor}"
}
}
```
***
### Skill Deleted
| Detail | Specification |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Emitted when** | Skills are removed from the TechWolf vocabulary, or Custom Skills are deleted. |
| **Expected frequency** | Monthly-quarterly (per Skill) |
| **Suggested action** | The Skill will no longer be available from the SkillEngine API (404). To handle out-of-order events, you can verify with [GET /taxonomy/skills/\{skill\_id}](/reference/latest/Taxonomy/TaxonomySkills/get-taxonomy-skills-skill-id) and propagate the deletion. |
**Event type:** `ai.techwolf.taxonomy.skill.deleted.v1`
**Event data**
| Field | Description |
| ----------------- | ------------------------------------------------------------------------------------------- |
| `tenant_name` | Identifies the tenant. |
| `external_id` | Identifies the Skill. |
| `external_vendor` | Indicates the Skill's vendor; use as the vendor query parameter when verifying via the API. |
```json theme={null}
{
"specversion": "1.0",
"type": "ai.techwolf.taxonomy.skill.deleted.v1",
"source": "https://{tenant}.{region}.techwolf.ai/taxonomy/skills/{skill_external_id}",
"id": "{event_uuid}",
"time": "2024-01-15T10:30:00Z",
"data": {
"tenant_name": "{tenant}",
"external_id": "{skill_external_id}",
"external_vendor": "{skill_external_vendor}"
}
}
```
***
### Taxonomy Updated
| Detail | Specification |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Emitted when** | The tenant's Skills Taxonomy changes or when the vocabulary is updated. |
| **Expected frequency** | Weekly (per tenant) |
| **Suggested action** | Retrieve Taxonomy changes from the SkillEngine API ([POST /taxonomy/export](/reference/latest/Export/TaxonomyExport/post-taxonomy-export)). Filter by `operation_type` to get only the kind of change you need; use `external_id` from the event to request the specific change that triggered the webhook. |
**Event type:** `ai.techwolf.taxonomy.updated.v1`
**Event data**
| Field | Description |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `tenant_name` | Identifies the tenant. |
| `operation_type` | Type of change; use to filter when calling the taxonomy or vocabulary export API. See [POST /taxonomy/export](/reference/latest/Export/TaxonomyExport/post-taxonomy-export) for a full list of values. |
| `external_id` | Identifies the specific change; pass when calling the taxonomy export API to fetch only that change. |
```json theme={null}
{
"specversion": "1.0",
"type": "ai.techwolf.taxonomy.updated.v1",
"source": "https://{tenant}.{region}.techwolf.ai/taxonomy/export",
"id": "{event_uuid}",
"time": "2024-01-15T10:30:00Z",
"data": {
"tenant_name": "{tenant}",
"operation_type": "{operation_type}",
"external_id": "{operation_external_id}"
}
}
```
***
### Health Check
| Detail | Specification |
| -------------------- | ----------------------------------------------------------- |
| **Emitted when** | TechWolf checks that your webhook consumer is live. |
| **Suggested action** | Respond with a 2XX status code. No business logic required. |
**Payload format**
```json theme={null}
{
"specversion": "1.0",
"type": "ai.techwolf.health_check",
"source": "https://{tenant}.{region}.techwolf.ai/",
"id": "{event_uuid}",
"time": "2024-01-15T10:30:00Z",
"data": {}
}
```