Events

Add a webhook endpoint

Changed on

Up to 10 per account. The URL must be public https; private, loopback, and link-local addresses are refused, the address is checked again on every delivery, and redirects are not followed. Each delivery is a POST with the event as JSON and a X-RecruitMCP-Signature header: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<exact request body>" with the endpoint secret>. Reject a delivery whose t is more than five minutes old. Failed deliveries are retried with backoff for about a day; use the event id to ignore duplicates.

Scope: account:manage. Acts on the account; keys bound to a customer are refused.

post/v1/webhook-endpoints

Request

  • Base URL: https://api.recruitmcp.com
  • URL: https://api.recruitmcp.com/v1/webhook-endpoints
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL https://recruitmcp.com/oauth/authorize, token URL https://recruitmcp.com/oauth/token, scopes: account:manage)

Headers

Idempotency-Keystring

Optional on this route. At most 128 characters. When present, the same key and body replays the first response for 24 hours. A different body is 409 idempotency_key_reused. A second call waits for the first and replays it. Omit the header to run the request normally.

RecruitMCP-Version'2026-10-13'

API version. Defaults to the version the key was created with. Supported: 2026-10-13.

Request body

urlstring

Public https URL. Private and loopback addresses are refused.

eventsstring[]

Default ["*"].

customer_idstring nullable
descriptionstring nullable
status'enabled' | 'disabled'

Example request

{
  "url": "https://hooks.example.com/recruitmcp",
  "events": [
    "job.completed",
    "reply.received"
  ]
}

Response

Created. The signing secret is shown once.

idstring required
object'webhook_endpoint' required
urlstring required
eventsstring[] required

Event types, or ["*"] for all.

customer_idstring nullable

Only events from this customer.

descriptionstring nullable
status'enabled' | 'disabled' required
secret_hintstring

Start of the signing secret, to tell secrets apart.

created_atstring date-time
updated_atstring date-time
secretstring required

Signing secret. Shown on create and rotate only.

Changes

  • ad27b35513a6Revision changes
    • warning

      added the new approval_forced enum value to the / response property for the response status

    • warning

      added the new approval_forced enum value to the / response property for the response status

    • warning

      added the new approval_forced enum value to the / response property for the response status

    • warning

      added the new approval_forced enum value to the / response property for the response status

    • warning

      added the new approval_forced enum value to the / response property for the response status