Skip to main content

​
Overview

Talview webhooks deliver event payloads to your infrastructure when candidate, assessment, scheduling, or payment changes happen. Before you can receive any hook, you must register an application, expose an HTTPS endpoint, and subscribe that application to one or more event types via the Graph API actions (hook_register_app, hook_subscribe). Tenant or platform administrator privileges are required.

​
Registration Workflow

  1. Create a hook application – call hook_register_app with a human-readable name (for example, the system that will consume events).
  2. Provision your endpoint – host a publicly reachable HTTPS URL, decide which HTTP method (POST, PUT, or PATCH) and headers you support, and plan for retries/signature validation.
  3. Subscribe to event types – invoke hook_subscribe per event_type_name, passing the application ID, endpoint URL, and optional overrides for method or transport.
  4. Validate delivery – trigger a lower-risk event (for example, create a test record) or use the re-trigger action to confirm you log responses correctly.
  5. Operate the lifecycle – disable, re-trigger, or unsubscribe via the companion actions as needed when rotating endpoints.

​
Registration API Inputs

Provide a single field when registering:
  • name: String. Display name for the consuming system; appears in admin consoles and audit logs.
type RegisterAppInput = {
  name: string;
};

​
Registration Payload Response Shape

Successful registration returns identifiers and audit metadata. Use the numeric id when subscribing. 
type RegisterAppResult = {
  id: number;
  uuid: string;
  name: string;
  created_at: string; // ISO timestamp
  created_by: number;
  updated_at?: string | null;
  updated_by?: number | null;
};

​
Registration Response Example

Successful registration returns identifiers and audit metadata. 
{
  "data": {
    "hook_register_app": {
      "id": 1,
      "uuid": "df4e18e2-4a36-403c-9081-5c7cb415fc16",
      "name": "Webhook QA Harness",
      "created_at": "2026-04-06T06:44:15.375006+00:00",
      "created_by": 1,
      "updated_at": null,
      "updated_by": null
    }
  }
}

​
Subscription Options

  • Graph API action (hook_subscribe): Preferred programmatic path; send a GraphQL mutation to the Hasura endpoint with authenticated admin credentials.

​
Subscription API Inputs

Each subscription binds one event type to one endpoint target. Required and optional fields mirror the Joi schema used by the Lambda handler.
  • event_type_name: String identifier (e.g., ae_test_instance_created) from the approved enum list.
  • url: HTTPS endpoint the platform will call.
  • application_id: Integer referencing the registered app.
  • method (optional): One of POST, PUT, PATCH; defaults to POST.
  • transport (optional): Transport enum; currently only HTTP is supported and used by default.
type SubscribeInput = {
  event_type_name: string;
  url: string;
  application_id: number;
  method?: 'POST' | 'PUT' | 'PATCH';
  transport?: 'HTTP';
};

​
Subscription Payload Response Shape

The action returns the saved subscription, including its unique identifiers and the event metadata snapshot. 
type SubscribeResult = {
  id: number;
  uuid: string;
  is_enabled: boolean;
  event_type: {
    id: number;
    name: string;
    verb: string;
    resource_type: string;
    service: string;
    schema: Record<string, unknown> | null;
  };
};

​
Subscription Response Example

The response to the graphql query will be of the following shape 
{
  "data": {
    "hook_subscribe": {
      "id": 3,
      "uuid": "03778579-a4c9-460d-b340-8759adb5beaf",
      "is_enabled": true,
      "event_type": {
        "id": 10,
        "name": "session.instance.created",
        "service": "session",
        "resource_type": "instance",
        "verb": "created",
        "schema": {}
      }
    }
  }
}

​
Creating a Subscription

Use the Graph API mutation below after registering your app. Replace the variables with your application ID, endpoint URL, and event type. When omitted, method becomes POST and transport becomes HTTP. 
mutation HookSubscribe(
  $event_type_name: String!
  $url: String!
  $application_id: Int!
  $method: String!
  $transport: String!
) {
  hook_subscribe(
    event_type_name: $event_type_name
    url: $url
    application_id: $application_id
    method: $method
    transport: $transport
  ) {
    id
    uuid
    is_enabled
    event_type {
      id
      name
      service
      resource_type
      verb
      schema
    }
  }
}
Example variables: 
{
  "event_type_name": "ae_test_instance_created",
  "url": "https://hooks.example.com/talview",
  "application_id": 42,
  "method": "POST"
}

​
Managing Existing Subscriptions

  • Disable or delete: Use the hook_unsubscribe action with the subscription uuid when retiring an endpoint.
  • Re-trigger deliveries: hook_re_trigger lets platform admins replay events (event_type_name + record id) to facilitate recovery or testing.

​
Testing & Verification

  • Trigger a known event in a staging tenant to observe the payload structure before enabling production subscriptions.
  • Confirm your endpoint returns a 2xx status within Talview’s timeout to prevent retries.
  • Store the uuid so you can map incoming deliveries back to the subscription configuration for troubleshooting.

​
Troubleshooting

  • Invalid input: The actions return 422 Unprocessable Entity when a required field is missing or event_type_name is outside the allow list.
  • Permission denied: Ensure the auth token carries TENANT_ADMIN or PLATFORM_ADMIN; other roles cannot call these actions.
  • Duplicate endpoint logic: The platform allows multiple subscriptions to the same URL; use your own idempotency logic to suppress duplicate downstream processing if needed.
  • Endpoint unreachable: Retries continue until the service marks the target as failed—monitor your logs and update the subscription with a working URL before re-triggering events.
  • docs/graph-api-reference/webhooks/overview.mdx – transport behavior, retry schedule, and event catalog.
  • Individual hook docs (for example, ae_test_instance_created.mdx) – payload contracts and sample data.