Webhooks

Update Webhook

Changed on

Replace a webhook's settings: target URL, saved search, description, one event per company, and daily event limit. Send every setting you want to keep, because one left out goes back to its default (no daily limit, for example), so read the webhook first. The signing secret and the event types only change when sent. To pause or resume a webhook, change its status instead.

patch/v0/webhooks/{webhook_id}

Request

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

Path parameters

webhook_idinteger required

ID of the webhook

Example:123

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. Omit to keep current value; set to null to remove.

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