Webhooks

Create Webhook

Changed on

Create a webhook on a saved search: each new record the search matches is sent as an HTTP POST to the URL you give, and every record sent consumes credits. Use it when the user wants new matches delivered to their own system. Check the URL first with a test event, and size the daily event limit from the saved search's estimated volume.

post/v0/webhooks

Request

  • Base URL
    https://api.theirstack.com
  • URL
    https://api.theirstack.com/v0/webhooks
  • Auth
    HTTP bearer

Request body

urlstring uri required

URL of the webhook

search_idinteger required

ID of the search that the webhook is listening to.

descriptionstring nullable

Description of the webhook

listening_start_timestring date-time nullable

Date when the webhook started listening for events. If listening_start_time is None, the webhook will listen to all events matching the search query regardless of when they occurred.

trigger_once_per_companyboolean

Only for webhook type ='job.new'. If true, Company A with 5 jobs → 1 event triggered. If false, Company A with 5 jobs → 5 events triggered

active_event_typesWebhookEventType[] nullable

Event types this webhook subscribes to. If None, defaults to the search type's primary event (job_new for jobs, company_new for companies).

max_events_per_dayinteger nullable

Most new records the webhook takes on per UTC day, or null for no cap. A job webhook counts jobs: each can send its job.new and, when it closes, its job.closed, so a job costs at most two credits. Records over it are dropped, never sent, charged or queued for the next day. Minimum 1: to send nothing, disable the webhook.

secretstring nullable

Secret used to sign webhook payloads with HMAC-SHA256. If set, deliveries include an X-TheirStack-Signature-256 header.

Example request

{
  "url": "https://example.com/webhook",
  "search_id": 123,
  "description": "Webhook for new jobs",
  "listening_start_time": "2024-01-01T00:00:00Z",
  "trigger_once_per_company": true,
  "max_events_per_day": 500
}

Response

Successful Response

urlstring uri required

URL of the webhook

search_idinteger required

ID of the search that the webhook is listening to.

descriptionstring nullable

Description of the webhook

listening_start_timestring date-time nullable

Date when the webhook started listening for events. If listening_start_time is None, the webhook will listen to all events matching the search query regardless of when they occurred.

trigger_once_per_companyboolean

Only for webhook type ='job.new'. If true, Company A with 5 jobs → 1 event triggered. If false, Company A with 5 jobs → 5 events triggered

active_event_typesWebhookEventType[] required
max_events_per_dayinteger nullable

Most new records the webhook takes on per UTC day, or null for no cap. A job webhook counts jobs: each can send its job.new and, when it closes, its job.closed, so a job costs at most two credits. Records over it are dropped, never sent, charged or queued for the next day. Minimum 1: to send nothing, disable the webhook.

idinteger required
user_idinteger required
team_idinteger required
is_activeboolean required
is_archivedboolean required
created_atstring date-time required
updated_atstring date-time required
search_namestring required
webhook_type'jobs' | 'companies' required
scanning_frequencystring

Scanning frequency for the webhook

has_secretboolean required
event_type'job_new' | 'company_new' | 'job_closed' required

Example response

{
  "url": "https://example.com/webhook",
  "search_id": 123,
  "description": "Webhook for new jobs",
  "listening_start_time": "2024-01-01T00:00:00Z",
  "trigger_once_per_company": true,
  "max_events_per_day": 500
}

Changes

  • 16937613a4ecRevision changes
    • breaking

      the / request property's min was increased to 1.00

  • 7b32949ee99eRevision changes
    • info

      added the new optional request property

    • info

      added the optional property to the response with the status