Create a webhook

Have Ploti POST to an https URL whenever one of the member's data or research requests changes: a dataset delivered or failed, a question waiting on their answer, a research request's report ready or its answer in. Use it to wake a routine or alert the user wherever they are instead of polling. Each POST is JSON {id, type, timestamp, data} (for a Data Feeds subscription's webhook, the feed event itself: {id, type, createdAt, subscriptionId, data}) signed with Standard Webhooks (webhook-id, webhook-timestamp, webhook-signature headers) under the returned secret, which is shown once; the reply carries the webhook's id, url, description, header name and creation time beside it. Docs: https://www.ploti.ai/docs/mcp/webhooks. When the receiver needs its own credential (a routine's bearer key), pass it as header; it is sent with every POST and never shown again. A member may have 20 webhooks. Events: data_request.sourcing, .matched, .checkpoint_released (first results), .ready, .failed, .cancelled, .paid_source, .cycle_refused, .question (Ploti needs the member's answer) and .question_reminder; research_request.report_ready (the data check reported what is there and what is missing), .question (the data check needs the member's answer; data.questions has the questions, and answer_research_request_questions sends the answers), .answered (data.answer) and .needs_attention (the research cannot finish on its own); data.url opens the request in Ploti. dataset.updated: a dataset the member watches (watch_dataset) has a new version; data.id is the dataset, data.version and data.promotedAt the new version, data.changeLog and data.counts what it added, changed and removed (list_dataset_changes lists those rows).

post/v1/webhooks

Request

  • Base URL: https://api.ploti.ai
  • URL: https://api.ploti.ai/v1/webhooks
  • Auth: HTTP bearer

Headers

Idempotency-Keystring

Any unique value, such as a UUID. A retry with the same key within a day returns the first answer instead of creating again; the same key with a different body is refused as idempotency_conflict.

Request body

urlstring uri required

The https address Ploti POSTs each event to; it must take JSON from the public internet.

descriptionstring

What the receiver is for, shown beside the webhook in Ploti, e.g. 'Nightly permit digest routine'.

subscriptionIdstring

A Data Feeds subscription: the webhook then receives that subscription's feed.* events instead of request events.

eventsstring[]

With subscriptionId, only these feed event types; every one when left out.

Response

Created

secretstring required

Changes

No recorded changes to this operation across all 1 revision of this API.