#Webhooks

Webhooks are how TechWolf tells an organisation's systems that something has changed, the moment it changes. TechWolf sends a notification to an endpoint the organisation exposes. The notification says what changed, for example which employee's skill profile was updated, so the receiving system knows what to act on and can fetch the new data.

That is what lets an organisation build real-time integrations and automations on TechWolf data: each change triggers the work, and only the data that changed is revisited.

#Key attributes

#How it works

The organisation exposes an HTTPS endpoint and registers it with TechWolf, together with the event types it wants to receive. When a subscribed change happens, TechWolf sends the notification in the CloudEvents format; the consumer verifies it, acknowledges receipt, and fetches the changed resource from the SkillEngine API.

Webhooks make changes visible in near real time. A scheduled reconciliation alongside them is what keeps two systems aligned: it re-reads both sides, settles any difference, and closes the gap left when an endpoint was unavailable for the whole of a delivery's retries. A notification signals that something changed, not what the change was. The current state, and the history behind a profile, come from the SkillEngine API.

Signed-in customers can find how to set up a webhook, verify its signature, handle deliveries and re-send events in the guides listed under Related pages.

#Webhook status

A webhook is Active, Paused or Disabled. A new webhook starts paused, and receives events once it is enabled in the Console, which first sends it a health check that has to pass. An organisation pauses a webhook to stop its deliveries for a while, for example during maintenance of its endpoint, and enables it again afterwards.

Delivery problems are handled so that none goes unnoticed and no event is lost for good. A temporary problem is retried. A problem that retrying cannot fix makes TechWolf disable the webhook and tell the organisation, and the events of that time stay available to be sent again once the endpoint is fixed. These are the responses that point to such a problem, because they come from the webhook's configuration:

A temporary problem, such as a 5XX status, a 408, a 429 or an endpoint that is too slow to respond, never disables a webhook. TechWolf disables it once at least five events failed with one of the responses above, with no successful delivery since, and the first of those failures is at least 24 hours old. Note that the hourly health check counts too, so a webhook with few events is also disabled when its endpoint stops accepting requests.

When TechWolf disables a webhook, the organisation's integration managers in the Console are notified by email and in the Console. The webhook's page says which response the endpoint returned and what to check. While the webhook is disabled, its events are not sent. After the cause is fixed, the webhook is re-enabled in the Console, which again sends a health check first, and the events it missed are re-sent from its page.

TechWolf keeps every event of a webhook, with its delivery attempts, for 30 days. In that time the events are listed on the webhook's page in the Console, and any of them can be sent again.

#Event types

Every notification has an event type, which says what changed, and a data object, which holds the tenant and resource identifiers needed to fetch that change from the SkillEngine API. The specifications below are grouped by entity, and each one gives when the event is emitted, its expected frequency, the suggested consumer action and the payload format of the latest version of the event. You only need to support the event types you consume; only the health check event is required for all consumers.

The skill events and the taxonomy event differ in granularity. The three skill events (created, updated and deleted) fire for one skill at a time and point you at that skill's endpoint. The taxonomy event fires for the tenant's taxonomy as a whole and points you at the taxonomy changes export, where each event corresponds to a single operation (identified by external_id).

The expected frequency is expressed per affected entity (for example per employee or per job), so this is not the total number of webhooks per day. Note that this is only a high-level indication; the actual frequency depends on the activity levels in the SkillEngine API and in any linked system, such as the TechWolf Skill Assistant, the TechWolf Console or external platforms with integrations. As for when the events are emitted, TechWolf delivers an event at least once for each of the triggers specified for it, and may also send it in other situations.

TechWolf may add new fields to existing webhook versions, for example extra fields in the data object. Your endpoint should tolerate unknown fields and not break when new ones are sent.

The event types are:

• Employee: Skill profile updated, Suggested skill profile updated
• Job: Skill profile updated, Suggested skill profile updated
• Course: Skill profile updated
• Skill vocabulary: Skill created, Skill updated, Skill deleted
• Taxonomy: Taxonomy updated
• Health check: Health check

#Employee skill profile updated

Note that 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 and fetch the skill profile by external_id, without special-casing them. 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

{
    "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

Note that this event covers suggested skills only (inferred, not yet validated or rejected). It is separate from Employee skill profile updated, which covers changes to the validated skill profile.

Event type: ai.techwolf.employee.skill_profile.suggested_updated.v1

{
    "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

Note that 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 and fetch the skill profile by external_id, without special-casing them. 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

{
    "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

Note that this event covers suggested skills only (inferred, not yet validated or rejected). It is separate from Job skill profile updated, which covers changes to the validated skill profile.

Event type: ai.techwolf.job_architecture.job.skill_profile.suggested_updated.v1

{
    "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

Event type: ai.techwolf.course.skill_profile.updated.v1

{
    "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

Event type: ai.techwolf.taxonomy.skill.created.v1

{
    "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

Event type: ai.techwolf.taxonomy.skill.updated.v1

{
    "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

Event type: ai.techwolf.taxonomy.skill.deleted.v1

{
    "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

Note that a single vocabulary update can send many of these events at once, as every skill it adds, renames, changes the description of or removes results in its own event. The expected frequency above therefore says little about the peak load on your endpoint. Deliveries that still fail after all retries are lost, so make sure your endpoint can handle such a burst, and run a periodic reconciliation alongside the webhooks to catch anything that was missed.

Event type: ai.techwolf.taxonomy.updated.v1

{
    "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

This event is required for all endpoints. The requests are signed like any other webhook request, and an hourly health check that your endpoint rejects counts towards disabling the webhook, like any other delivery.

Event type: ai.techwolf.health_check

{
    "specversion": "1.0",
    "type": "ai.techwolf.health_check",
    "source": "https://{tenant}.{region}.techwolf.ai/",
    "id": "{event_uuid}",
    "time": "2024-01-15T10:30:00Z",
    "data": {}
}

#Prerequisites

Webhooks are part of TechWolf's output integrations. They require an HTTPS endpoint operated by the organisation and SkillEngine API access to fetch the changed resources. TechWolf sends webhooks from a fixed set of IP addresses per region. If the organisation's network filters inbound traffic, the organisation must allowlist the addresses for its region.

#Availability

• Console: webhooks are configured, tested, paused and enabled in the Console, as an outbound integration in the Integration Manager. The Console also lists each webhook's events of the last 30 days, and sends them again on request.