> For the complete documentation index, see [llms.txt](https://help.paintscout.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.paintscout.com/developers/webhooks.md).

# Webhooks

## GET /webhooks

> List Webhooks

```json
{"openapi":"3.0.0","info":{"title":"Core API","version":"v2"},"servers":[{"url":"https://openapi.paintscout.com/v2"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"Webhook":{"properties":{"events":{"type":"array","additionalProperties":false,"description":"A list of events covering events the Webhook is subscripted to. Allowed values: company-created, company-tags-changed, contact-created, contact-tags-changed, deal-created, deal-tags-changed, deal-stage-changed, lead-form-submitted, event-created, event-updated, event-cancelled, event-completed, event-progress-updated, event-crew-changed, task-created, task-completed, quote-created, invoice-created, quote-sent, invoice-sent, send-work-order, quote-accepted, quote-additional-work-accepted, invoice-additional-work-accepted, quote-declined, quote-status-changed, quote-owner-changed, quote-tags-changed, quote-viewed, invoice-viewed, quote-updated, invoice-updated, payment-received. payment-received fires once for each payment recorded on a quote or invoice (card, ACH, manual, or Wisetack); its body carries the `quote` (and `invoice`, for an invoice) plus a `payment` object with `id`, `type` (the payment method), `amount` (dollars, including any surcharge), `surcharge`, `deposit`, `date` (epoch milliseconds), `note`, `status` and `provider` (`stripe`, `payrix`, `wisetack` or `manual`). Refunds and failed payments do not fire it.","items":{"type":"string","enum":["company-created","company-tags-changed","contact-created","contact-tags-changed","deal-created","deal-tags-changed","deal-stage-changed","lead-form-submitted","event-created","event-updated","event-cancelled","event-completed","event-progress-updated","event-crew-changed","task-created","task-completed","quote-created","invoice-created","quote-sent","invoice-sent","send-work-order","quote-accepted","quote-additional-work-accepted","invoice-additional-work-accepted","quote-declined","quote-status-changed","quote-owner-changed","quote-tags-changed","quote-viewed","invoice-viewed","quote-updated","invoice-updated","payment-received"]}}}},"Timestamp":{"type":"object","additionalProperties":false,"properties":{"created":{"type":"number","description":"The timestamp when this entity was created"},"updated":{"type":"number","description":"The timestamp when this entity was last updated"}}},"Error":{"type":"object","additionalProperties":false,"properties":{"errors":{"type":"array","items":{"type":"string"},"description":"Array of error messages"}}}}},"paths":{"/webhooks":{"get":{"summary":"List Webhooks","operationId":"listWebhooks","tags":["Webhooks"],"parameters":[{"name":"page","in":"query","description":"Page number to fetch, 1-indexed. Defaults to 1.","schema":{"type":"integer","format":"int32"}},{"name":"perPage","in":"query","description":"Number of results per page (1-100). Defaults to the API's standard page size if omitted.","schema":{"type":"integer","format":"int32"}}],"responses":{"200":{"description":"List of webhooks","content":{"application/json":{"schema":{"type":"object","properties":{"totalRows":{"type":"number"},"rows":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","description":"A unique ID for the Webhook."},"url":{"type":"string","description":"The URL of the webhook, which will receive requests with data for any events fired that fall within the events of the Webhook."},"events":{"type":"array","$ref":"#/components/schemas/Webhook/properties/events"},"params":{"type":"object","nullable":true,"additionalProperties":false,"description":"An optional object of key-value pairs used to customize webhook trigger behavior.","properties":{"isInvoice":{"type":"boolean","description":"Whether or not the quote webhook is only to toggle for invoices. Only applicable for quote-related webhooks. For payment-received, true sends only invoice payments, false sends only quote payments, and leaving it unset sends both."},"quoteTypes":{"type":"array","description":"A list of quote types (by Id or Label) to filter quote-related webhooks. Only applicable for quote-related webhooks.","items":{"type":"string"}},"quoteStatus":{"type":"array","description":"A list of quote statuses to filter quote-related webhooks. Only applicable for quote or invoice related webhooks.","items":{"type":"string"}},"eventTypes":{"type":"array","description":"A list of calendar event types (by Id or Label) to filter on. Only applicable for event-* webhooks.","items":{"type":"string"}},"stageIds":{"type":"array","description":"A list of Deal Stage Ids to filter deal-stage-changed webhooks.","items":{"type":"string"}},"tagsAdded":{"type":"array","description":"A list of tags, if any of these tags are added to the entity, the webhook will trigger.","items":{"type":"string"}},"tagsRemoved":{"type":"array","description":"A list of tags, if any of these tags are removed from the entity, the webhook will trigger.","items":{"type":"string"}}}},"token":{"type":"string","description":"Shared secret for this webhook. Generated for you if you do not supply one, and never changed unless you send a new value or rotate it. The full value is returned only by the create and rotate-token calls; every other response masks it as `••••` plus its last 4 characters, so store it when you receive it. PaintScout returns it verbatim on every delivery in the `Authorization` header as `Bearer <token>`, so you can confirm the request came from PaintScout, and also uses it as the HMAC-SHA256 key to sign the request body. Each delivery carries `X-PaintScout-Timestamp` (Unix seconds) and `X-PaintScout-Signature` in the form `v1=<hex digest>`, where the digest is computed over the string `<timestamp>.<raw request body>`. Verify against the exact bytes you received, before parsing the JSON, and compare the digests with a constant-time function such as Node's `crypto.timingSafeEqual` rather than `===`. The timestamp is regenerated on each delivery attempt, so a retried event carries a newer timestamp than the original. Every delivery also carries an `X-PaintScout-Event-Id` header, which stays the same across retries of the same event — use it to deduplicate deliveries. A failed delivery is retried up to 6 times, about 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours and 12 hours after the previous attempt (each wait varies by up to 10%), so the last attempt is about 21 hours after the first. It is retried when your endpoint returns a 5xx, 408 or 429 status or the request fails with a network error such as a timeout or a reset connection. Other 4xx statuses, TLS certificate errors and invalid URLs are not retried. After the last retry the event is not sent again on its own. List a webhook's events with `GET /webhooks/{id}/events` and send one again with `POST /webhook-events/{id}/redeliver`, or use the list endpoints (for example `GET /quotes` and `GET /invoices`) to catch up after an outage."},"enabled":{"type":"boolean","description":"Whether or not the Webhook is enabled/active."},"timestamp":{"$ref":"#/components/schemas/Timestamp"}},"required":["id","url","events"]}}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not Authorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```

## POST /webhooks

> Create Webhook

```json
{"openapi":"3.0.0","info":{"title":"Core API","version":"v2"},"servers":[{"url":"https://openapi.paintscout.com/v2"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"Webhook":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","description":"A unique ID for the Webhook. Ignored when creating & updating webhooks."},"url":{"type":"string","description":"The URL of the webhook, which will receive requests with data for any events fired that fall within the events of the Webhook."},"events":{"type":"array","additionalProperties":false,"description":"A list of events covering events the Webhook is subscripted to. Allowed values: company-created, company-tags-changed, contact-created, contact-tags-changed, deal-created, deal-tags-changed, deal-stage-changed, lead-form-submitted, event-created, event-updated, event-cancelled, event-completed, event-progress-updated, event-crew-changed, task-created, task-completed, quote-created, invoice-created, quote-sent, invoice-sent, send-work-order, quote-accepted, quote-additional-work-accepted, invoice-additional-work-accepted, quote-declined, quote-status-changed, quote-owner-changed, quote-tags-changed, quote-viewed, invoice-viewed, quote-updated, invoice-updated, payment-received. payment-received fires once for each payment recorded on a quote or invoice (card, ACH, manual, or Wisetack); its body carries the `quote` (and `invoice`, for an invoice) plus a `payment` object with `id`, `type` (the payment method), `amount` (dollars, including any surcharge), `surcharge`, `deposit`, `date` (epoch milliseconds), `note`, `status` and `provider` (`stripe`, `payrix`, `wisetack` or `manual`). Refunds and failed payments do not fire it.","items":{"type":"string","enum":["company-created","company-tags-changed","contact-created","contact-tags-changed","deal-created","deal-tags-changed","deal-stage-changed","lead-form-submitted","event-created","event-updated","event-cancelled","event-completed","event-progress-updated","event-crew-changed","task-created","task-completed","quote-created","invoice-created","quote-sent","invoice-sent","send-work-order","quote-accepted","quote-additional-work-accepted","invoice-additional-work-accepted","quote-declined","quote-status-changed","quote-owner-changed","quote-tags-changed","quote-viewed","invoice-viewed","quote-updated","invoice-updated","payment-received"]}},"params":{"type":"object","nullable":true,"additionalProperties":false,"description":"An optional object of key-value pairs used to customize webhook trigger behavior.","properties":{"isInvoice":{"type":"boolean","description":"Whether or not the quote webhook is only to toggle for invoices. Only applicable for quote-related webhooks. For payment-received, true sends only invoice payments, false sends only quote payments, and leaving it unset sends both."},"quoteTypes":{"type":"array","description":"A list of quote types (by Id or Label) to filter quote-related webhooks. Only applicable for quote-related webhooks.","items":{"type":"string"}},"quoteStatus":{"type":"array","description":"A list of quote statuses to filter quote-related webhooks. Only applicable for quote or invoice related webhooks.","items":{"type":"string"}},"eventTypes":{"type":"array","description":"A list of calendar event types (by Id or Label) to filter on. Only applicable for event-* webhooks.","items":{"type":"string"}},"stageIds":{"type":"array","description":"A list of Deal Stage Ids to filter deal-stage-changed webhooks.","items":{"type":"string"}},"tagsAdded":{"type":"array","description":"A list of tags, if any of these tags are added to the entity, the webhook will trigger.","items":{"type":"string"}},"tagsRemoved":{"type":"array","description":"A list of tags, if any of these tags are removed from the entity, the webhook will trigger.","items":{"type":"string"}}}},"token":{"type":"string","description":"Shared secret for this webhook. Generated for you if you do not supply one, and never changed unless you send a new value or rotate it. The full value is returned only by the create and rotate-token calls; every other response masks it as `••••` plus its last 4 characters, so store it when you receive it. PaintScout returns it verbatim on every delivery in the `Authorization` header as `Bearer <token>`, so you can confirm the request came from PaintScout, and also uses it as the HMAC-SHA256 key to sign the request body. Each delivery carries `X-PaintScout-Timestamp` (Unix seconds) and `X-PaintScout-Signature` in the form `v1=<hex digest>`, where the digest is computed over the string `<timestamp>.<raw request body>`. Verify against the exact bytes you received, before parsing the JSON, and compare the digests with a constant-time function such as Node's `crypto.timingSafeEqual` rather than `===`. The timestamp is regenerated on each delivery attempt, so a retried event carries a newer timestamp than the original. Every delivery also carries an `X-PaintScout-Event-Id` header, which stays the same across retries of the same event — use it to deduplicate deliveries. A failed delivery is retried up to 6 times, about 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours and 12 hours after the previous attempt (each wait varies by up to 10%), so the last attempt is about 21 hours after the first. It is retried when your endpoint returns a 5xx, 408 or 429 status or the request fails with a network error such as a timeout or a reset connection. Other 4xx statuses, TLS certificate errors and invalid URLs are not retried. After the last retry the event is not sent again on its own. List a webhook's events with `GET /webhooks/{id}/events` and send one again with `POST /webhook-events/{id}/redeliver`, or use the list endpoints (for example `GET /quotes` and `GET /invoices`) to catch up after an outage."},"enabled":{"type":"boolean","description":"Whether or not the Webhook is enabled/active."},"timestamp":{"$ref":"#/components/schemas/Timestamp"},"health":{"$ref":"#/components/schemas/WebhookHealth"}},"required":["url","events"]},"Timestamp":{"type":"object","additionalProperties":false,"properties":{"created":{"type":"number","description":"The timestamp when this entity was created"},"updated":{"type":"number","description":"The timestamp when this entity was last updated"}}},"WebhookHealth":{"type":"object","readOnly":true,"additionalProperties":false,"description":"Delivery health, computed when you read the webhook. Test pings (`POST /webhooks/{id}/test`) are left out of every value. Returned by `GET /webhooks/{id}` only. If the health lookup fails, every value is empty and `failing` is false.","properties":{"lastSuccessAt":{"type":"number","nullable":true,"description":"Epoch milliseconds of the newest successful delivery among the stored events, or null."},"lastFailureAt":{"type":"number","nullable":true,"description":"Epoch milliseconds of the newest failed or expired delivery among the stored events, or null."},"failed24h":{"type":"integer","description":"Events created in the last 24 hours that failed or expired."},"total24h":{"type":"integer","description":"Events created in the last 24 hours, not counting skipped events."},"failing":{"type":"boolean","description":"True when an event failed in the last 24 hours and none succeeded in that time."}},"required":["lastSuccessAt","lastFailureAt","failed24h","total24h","failing"]},"Error":{"type":"object","additionalProperties":false,"properties":{"errors":{"type":"array","items":{"type":"string"},"description":"Array of error messages"}}}}},"paths":{"/webhooks":{"post":{"summary":"Create Webhook","operationId":"createWebhook","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Webhook"}}}},"responses":{"200":{"description":"Details about the new Webhook","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Webhook"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not Authorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```

## GET /webhooks/{id}

> Retrieve Webhook

```json
{"openapi":"3.0.0","info":{"title":"Core API","version":"v2"},"servers":[{"url":"https://openapi.paintscout.com/v2"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"Webhook":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","description":"A unique ID for the Webhook. Ignored when creating & updating webhooks."},"url":{"type":"string","description":"The URL of the webhook, which will receive requests with data for any events fired that fall within the events of the Webhook."},"events":{"type":"array","additionalProperties":false,"description":"A list of events covering events the Webhook is subscripted to. Allowed values: company-created, company-tags-changed, contact-created, contact-tags-changed, deal-created, deal-tags-changed, deal-stage-changed, lead-form-submitted, event-created, event-updated, event-cancelled, event-completed, event-progress-updated, event-crew-changed, task-created, task-completed, quote-created, invoice-created, quote-sent, invoice-sent, send-work-order, quote-accepted, quote-additional-work-accepted, invoice-additional-work-accepted, quote-declined, quote-status-changed, quote-owner-changed, quote-tags-changed, quote-viewed, invoice-viewed, quote-updated, invoice-updated, payment-received. payment-received fires once for each payment recorded on a quote or invoice (card, ACH, manual, or Wisetack); its body carries the `quote` (and `invoice`, for an invoice) plus a `payment` object with `id`, `type` (the payment method), `amount` (dollars, including any surcharge), `surcharge`, `deposit`, `date` (epoch milliseconds), `note`, `status` and `provider` (`stripe`, `payrix`, `wisetack` or `manual`). Refunds and failed payments do not fire it.","items":{"type":"string","enum":["company-created","company-tags-changed","contact-created","contact-tags-changed","deal-created","deal-tags-changed","deal-stage-changed","lead-form-submitted","event-created","event-updated","event-cancelled","event-completed","event-progress-updated","event-crew-changed","task-created","task-completed","quote-created","invoice-created","quote-sent","invoice-sent","send-work-order","quote-accepted","quote-additional-work-accepted","invoice-additional-work-accepted","quote-declined","quote-status-changed","quote-owner-changed","quote-tags-changed","quote-viewed","invoice-viewed","quote-updated","invoice-updated","payment-received"]}},"params":{"type":"object","nullable":true,"additionalProperties":false,"description":"An optional object of key-value pairs used to customize webhook trigger behavior.","properties":{"isInvoice":{"type":"boolean","description":"Whether or not the quote webhook is only to toggle for invoices. Only applicable for quote-related webhooks. For payment-received, true sends only invoice payments, false sends only quote payments, and leaving it unset sends both."},"quoteTypes":{"type":"array","description":"A list of quote types (by Id or Label) to filter quote-related webhooks. Only applicable for quote-related webhooks.","items":{"type":"string"}},"quoteStatus":{"type":"array","description":"A list of quote statuses to filter quote-related webhooks. Only applicable for quote or invoice related webhooks.","items":{"type":"string"}},"eventTypes":{"type":"array","description":"A list of calendar event types (by Id or Label) to filter on. Only applicable for event-* webhooks.","items":{"type":"string"}},"stageIds":{"type":"array","description":"A list of Deal Stage Ids to filter deal-stage-changed webhooks.","items":{"type":"string"}},"tagsAdded":{"type":"array","description":"A list of tags, if any of these tags are added to the entity, the webhook will trigger.","items":{"type":"string"}},"tagsRemoved":{"type":"array","description":"A list of tags, if any of these tags are removed from the entity, the webhook will trigger.","items":{"type":"string"}}}},"token":{"type":"string","description":"Shared secret for this webhook. Generated for you if you do not supply one, and never changed unless you send a new value or rotate it. The full value is returned only by the create and rotate-token calls; every other response masks it as `••••` plus its last 4 characters, so store it when you receive it. PaintScout returns it verbatim on every delivery in the `Authorization` header as `Bearer <token>`, so you can confirm the request came from PaintScout, and also uses it as the HMAC-SHA256 key to sign the request body. Each delivery carries `X-PaintScout-Timestamp` (Unix seconds) and `X-PaintScout-Signature` in the form `v1=<hex digest>`, where the digest is computed over the string `<timestamp>.<raw request body>`. Verify against the exact bytes you received, before parsing the JSON, and compare the digests with a constant-time function such as Node's `crypto.timingSafeEqual` rather than `===`. The timestamp is regenerated on each delivery attempt, so a retried event carries a newer timestamp than the original. Every delivery also carries an `X-PaintScout-Event-Id` header, which stays the same across retries of the same event — use it to deduplicate deliveries. A failed delivery is retried up to 6 times, about 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours and 12 hours after the previous attempt (each wait varies by up to 10%), so the last attempt is about 21 hours after the first. It is retried when your endpoint returns a 5xx, 408 or 429 status or the request fails with a network error such as a timeout or a reset connection. Other 4xx statuses, TLS certificate errors and invalid URLs are not retried. After the last retry the event is not sent again on its own. List a webhook's events with `GET /webhooks/{id}/events` and send one again with `POST /webhook-events/{id}/redeliver`, or use the list endpoints (for example `GET /quotes` and `GET /invoices`) to catch up after an outage."},"enabled":{"type":"boolean","description":"Whether or not the Webhook is enabled/active."},"timestamp":{"$ref":"#/components/schemas/Timestamp"},"health":{"$ref":"#/components/schemas/WebhookHealth"}},"required":["url","events"]},"Timestamp":{"type":"object","additionalProperties":false,"properties":{"created":{"type":"number","description":"The timestamp when this entity was created"},"updated":{"type":"number","description":"The timestamp when this entity was last updated"}}},"WebhookHealth":{"type":"object","readOnly":true,"additionalProperties":false,"description":"Delivery health, computed when you read the webhook. Test pings (`POST /webhooks/{id}/test`) are left out of every value. Returned by `GET /webhooks/{id}` only. If the health lookup fails, every value is empty and `failing` is false.","properties":{"lastSuccessAt":{"type":"number","nullable":true,"description":"Epoch milliseconds of the newest successful delivery among the stored events, or null."},"lastFailureAt":{"type":"number","nullable":true,"description":"Epoch milliseconds of the newest failed or expired delivery among the stored events, or null."},"failed24h":{"type":"integer","description":"Events created in the last 24 hours that failed or expired."},"total24h":{"type":"integer","description":"Events created in the last 24 hours, not counting skipped events."},"failing":{"type":"boolean","description":"True when an event failed in the last 24 hours and none succeeded in that time."}},"required":["lastSuccessAt","lastFailureAt","failed24h","total24h","failing"]},"Error":{"type":"object","additionalProperties":false,"properties":{"errors":{"type":"array","items":{"type":"string"},"description":"Array of error messages"}}}}},"paths":{"/webhooks/{id}":{"get":{"summary":"Retrieve Webhook","operationId":"getWebhook","tags":["Webhooks"],"parameters":[{"name":"id","in":"path","description":"ID of the Webhooks","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Details about the webhooks","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Webhook"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not Authorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```

## PUT /webhooks/{id}

> Update Webhook

```json
{"openapi":"3.0.0","info":{"title":"Core API","version":"v2"},"servers":[{"url":"https://openapi.paintscout.com/v2"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"Webhook":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","description":"A unique ID for the Webhook. Ignored when creating & updating webhooks."},"url":{"type":"string","description":"The URL of the webhook, which will receive requests with data for any events fired that fall within the events of the Webhook."},"events":{"type":"array","additionalProperties":false,"description":"A list of events covering events the Webhook is subscripted to. Allowed values: company-created, company-tags-changed, contact-created, contact-tags-changed, deal-created, deal-tags-changed, deal-stage-changed, lead-form-submitted, event-created, event-updated, event-cancelled, event-completed, event-progress-updated, event-crew-changed, task-created, task-completed, quote-created, invoice-created, quote-sent, invoice-sent, send-work-order, quote-accepted, quote-additional-work-accepted, invoice-additional-work-accepted, quote-declined, quote-status-changed, quote-owner-changed, quote-tags-changed, quote-viewed, invoice-viewed, quote-updated, invoice-updated, payment-received. payment-received fires once for each payment recorded on a quote or invoice (card, ACH, manual, or Wisetack); its body carries the `quote` (and `invoice`, for an invoice) plus a `payment` object with `id`, `type` (the payment method), `amount` (dollars, including any surcharge), `surcharge`, `deposit`, `date` (epoch milliseconds), `note`, `status` and `provider` (`stripe`, `payrix`, `wisetack` or `manual`). Refunds and failed payments do not fire it.","items":{"type":"string","enum":["company-created","company-tags-changed","contact-created","contact-tags-changed","deal-created","deal-tags-changed","deal-stage-changed","lead-form-submitted","event-created","event-updated","event-cancelled","event-completed","event-progress-updated","event-crew-changed","task-created","task-completed","quote-created","invoice-created","quote-sent","invoice-sent","send-work-order","quote-accepted","quote-additional-work-accepted","invoice-additional-work-accepted","quote-declined","quote-status-changed","quote-owner-changed","quote-tags-changed","quote-viewed","invoice-viewed","quote-updated","invoice-updated","payment-received"]}},"params":{"type":"object","nullable":true,"additionalProperties":false,"description":"An optional object of key-value pairs used to customize webhook trigger behavior.","properties":{"isInvoice":{"type":"boolean","description":"Whether or not the quote webhook is only to toggle for invoices. Only applicable for quote-related webhooks. For payment-received, true sends only invoice payments, false sends only quote payments, and leaving it unset sends both."},"quoteTypes":{"type":"array","description":"A list of quote types (by Id or Label) to filter quote-related webhooks. Only applicable for quote-related webhooks.","items":{"type":"string"}},"quoteStatus":{"type":"array","description":"A list of quote statuses to filter quote-related webhooks. Only applicable for quote or invoice related webhooks.","items":{"type":"string"}},"eventTypes":{"type":"array","description":"A list of calendar event types (by Id or Label) to filter on. Only applicable for event-* webhooks.","items":{"type":"string"}},"stageIds":{"type":"array","description":"A list of Deal Stage Ids to filter deal-stage-changed webhooks.","items":{"type":"string"}},"tagsAdded":{"type":"array","description":"A list of tags, if any of these tags are added to the entity, the webhook will trigger.","items":{"type":"string"}},"tagsRemoved":{"type":"array","description":"A list of tags, if any of these tags are removed from the entity, the webhook will trigger.","items":{"type":"string"}}}},"token":{"type":"string","description":"Shared secret for this webhook. Generated for you if you do not supply one, and never changed unless you send a new value or rotate it. The full value is returned only by the create and rotate-token calls; every other response masks it as `••••` plus its last 4 characters, so store it when you receive it. PaintScout returns it verbatim on every delivery in the `Authorization` header as `Bearer <token>`, so you can confirm the request came from PaintScout, and also uses it as the HMAC-SHA256 key to sign the request body. Each delivery carries `X-PaintScout-Timestamp` (Unix seconds) and `X-PaintScout-Signature` in the form `v1=<hex digest>`, where the digest is computed over the string `<timestamp>.<raw request body>`. Verify against the exact bytes you received, before parsing the JSON, and compare the digests with a constant-time function such as Node's `crypto.timingSafeEqual` rather than `===`. The timestamp is regenerated on each delivery attempt, so a retried event carries a newer timestamp than the original. Every delivery also carries an `X-PaintScout-Event-Id` header, which stays the same across retries of the same event — use it to deduplicate deliveries. A failed delivery is retried up to 6 times, about 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours and 12 hours after the previous attempt (each wait varies by up to 10%), so the last attempt is about 21 hours after the first. It is retried when your endpoint returns a 5xx, 408 or 429 status or the request fails with a network error such as a timeout or a reset connection. Other 4xx statuses, TLS certificate errors and invalid URLs are not retried. After the last retry the event is not sent again on its own. List a webhook's events with `GET /webhooks/{id}/events` and send one again with `POST /webhook-events/{id}/redeliver`, or use the list endpoints (for example `GET /quotes` and `GET /invoices`) to catch up after an outage."},"enabled":{"type":"boolean","description":"Whether or not the Webhook is enabled/active."},"timestamp":{"$ref":"#/components/schemas/Timestamp"},"health":{"$ref":"#/components/schemas/WebhookHealth"}},"required":["url","events"]},"Timestamp":{"type":"object","additionalProperties":false,"properties":{"created":{"type":"number","description":"The timestamp when this entity was created"},"updated":{"type":"number","description":"The timestamp when this entity was last updated"}}},"WebhookHealth":{"type":"object","readOnly":true,"additionalProperties":false,"description":"Delivery health, computed when you read the webhook. Test pings (`POST /webhooks/{id}/test`) are left out of every value. Returned by `GET /webhooks/{id}` only. If the health lookup fails, every value is empty and `failing` is false.","properties":{"lastSuccessAt":{"type":"number","nullable":true,"description":"Epoch milliseconds of the newest successful delivery among the stored events, or null."},"lastFailureAt":{"type":"number","nullable":true,"description":"Epoch milliseconds of the newest failed or expired delivery among the stored events, or null."},"failed24h":{"type":"integer","description":"Events created in the last 24 hours that failed or expired."},"total24h":{"type":"integer","description":"Events created in the last 24 hours, not counting skipped events."},"failing":{"type":"boolean","description":"True when an event failed in the last 24 hours and none succeeded in that time."}},"required":["lastSuccessAt","lastFailureAt","failed24h","total24h","failing"]},"Error":{"type":"object","additionalProperties":false,"properties":{"errors":{"type":"array","items":{"type":"string"},"description":"Array of error messages"}}}}},"paths":{"/webhooks/{id}":{"put":{"summary":"Update Webhook","parameters":[{"name":"id","in":"path","description":"ID of the Webhook","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Webhook"}}}},"operationId":"updateWebhook","tags":["Webhooks"],"responses":{"200":{"description":"The updated webhook","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Webhook"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not Authorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```

## DELETE /webhooks/{id}

> Delete Webhook

```json
{"openapi":"3.0.0","info":{"title":"Core API","version":"v2"},"servers":[{"url":"https://openapi.paintscout.com/v2"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"Error":{"type":"object","additionalProperties":false,"properties":{"errors":{"type":"array","items":{"type":"string"},"description":"Array of error messages"}}}}},"paths":{"/webhooks/{id}":{"delete":{"summary":"Delete Webhook","parameters":[{"name":"id","in":"path","description":"ID of the Webhook","required":true,"schema":{"type":"string"}}],"operationId":"deleteWebhook","tags":["Webhooks"],"responses":{"204":{"description":"No Content"},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not Authorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```

## Rotate Webhook Token

> Replaces the webhook's signing token with a new generated value. The response is the only place the new token is shown in full; later reads return it masked. Deliveries sent after this call use the new token, so update your endpoint's verification before you rotate, or accept both tokens while you switch over.

```json
{"openapi":"3.0.0","info":{"title":"Core API","version":"v2"},"servers":[{"url":"https://openapi.paintscout.com/v2"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"Webhook":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","description":"A unique ID for the Webhook. Ignored when creating & updating webhooks."},"url":{"type":"string","description":"The URL of the webhook, which will receive requests with data for any events fired that fall within the events of the Webhook."},"events":{"type":"array","additionalProperties":false,"description":"A list of events covering events the Webhook is subscripted to. Allowed values: company-created, company-tags-changed, contact-created, contact-tags-changed, deal-created, deal-tags-changed, deal-stage-changed, lead-form-submitted, event-created, event-updated, event-cancelled, event-completed, event-progress-updated, event-crew-changed, task-created, task-completed, quote-created, invoice-created, quote-sent, invoice-sent, send-work-order, quote-accepted, quote-additional-work-accepted, invoice-additional-work-accepted, quote-declined, quote-status-changed, quote-owner-changed, quote-tags-changed, quote-viewed, invoice-viewed, quote-updated, invoice-updated, payment-received. payment-received fires once for each payment recorded on a quote or invoice (card, ACH, manual, or Wisetack); its body carries the `quote` (and `invoice`, for an invoice) plus a `payment` object with `id`, `type` (the payment method), `amount` (dollars, including any surcharge), `surcharge`, `deposit`, `date` (epoch milliseconds), `note`, `status` and `provider` (`stripe`, `payrix`, `wisetack` or `manual`). Refunds and failed payments do not fire it.","items":{"type":"string","enum":["company-created","company-tags-changed","contact-created","contact-tags-changed","deal-created","deal-tags-changed","deal-stage-changed","lead-form-submitted","event-created","event-updated","event-cancelled","event-completed","event-progress-updated","event-crew-changed","task-created","task-completed","quote-created","invoice-created","quote-sent","invoice-sent","send-work-order","quote-accepted","quote-additional-work-accepted","invoice-additional-work-accepted","quote-declined","quote-status-changed","quote-owner-changed","quote-tags-changed","quote-viewed","invoice-viewed","quote-updated","invoice-updated","payment-received"]}},"params":{"type":"object","nullable":true,"additionalProperties":false,"description":"An optional object of key-value pairs used to customize webhook trigger behavior.","properties":{"isInvoice":{"type":"boolean","description":"Whether or not the quote webhook is only to toggle for invoices. Only applicable for quote-related webhooks. For payment-received, true sends only invoice payments, false sends only quote payments, and leaving it unset sends both."},"quoteTypes":{"type":"array","description":"A list of quote types (by Id or Label) to filter quote-related webhooks. Only applicable for quote-related webhooks.","items":{"type":"string"}},"quoteStatus":{"type":"array","description":"A list of quote statuses to filter quote-related webhooks. Only applicable for quote or invoice related webhooks.","items":{"type":"string"}},"eventTypes":{"type":"array","description":"A list of calendar event types (by Id or Label) to filter on. Only applicable for event-* webhooks.","items":{"type":"string"}},"stageIds":{"type":"array","description":"A list of Deal Stage Ids to filter deal-stage-changed webhooks.","items":{"type":"string"}},"tagsAdded":{"type":"array","description":"A list of tags, if any of these tags are added to the entity, the webhook will trigger.","items":{"type":"string"}},"tagsRemoved":{"type":"array","description":"A list of tags, if any of these tags are removed from the entity, the webhook will trigger.","items":{"type":"string"}}}},"token":{"type":"string","description":"Shared secret for this webhook. Generated for you if you do not supply one, and never changed unless you send a new value or rotate it. The full value is returned only by the create and rotate-token calls; every other response masks it as `••••` plus its last 4 characters, so store it when you receive it. PaintScout returns it verbatim on every delivery in the `Authorization` header as `Bearer <token>`, so you can confirm the request came from PaintScout, and also uses it as the HMAC-SHA256 key to sign the request body. Each delivery carries `X-PaintScout-Timestamp` (Unix seconds) and `X-PaintScout-Signature` in the form `v1=<hex digest>`, where the digest is computed over the string `<timestamp>.<raw request body>`. Verify against the exact bytes you received, before parsing the JSON, and compare the digests with a constant-time function such as Node's `crypto.timingSafeEqual` rather than `===`. The timestamp is regenerated on each delivery attempt, so a retried event carries a newer timestamp than the original. Every delivery also carries an `X-PaintScout-Event-Id` header, which stays the same across retries of the same event — use it to deduplicate deliveries. A failed delivery is retried up to 6 times, about 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours and 12 hours after the previous attempt (each wait varies by up to 10%), so the last attempt is about 21 hours after the first. It is retried when your endpoint returns a 5xx, 408 or 429 status or the request fails with a network error such as a timeout or a reset connection. Other 4xx statuses, TLS certificate errors and invalid URLs are not retried. After the last retry the event is not sent again on its own. List a webhook's events with `GET /webhooks/{id}/events` and send one again with `POST /webhook-events/{id}/redeliver`, or use the list endpoints (for example `GET /quotes` and `GET /invoices`) to catch up after an outage."},"enabled":{"type":"boolean","description":"Whether or not the Webhook is enabled/active."},"timestamp":{"$ref":"#/components/schemas/Timestamp"},"health":{"$ref":"#/components/schemas/WebhookHealth"}},"required":["url","events"]},"Timestamp":{"type":"object","additionalProperties":false,"properties":{"created":{"type":"number","description":"The timestamp when this entity was created"},"updated":{"type":"number","description":"The timestamp when this entity was last updated"}}},"WebhookHealth":{"type":"object","readOnly":true,"additionalProperties":false,"description":"Delivery health, computed when you read the webhook. Test pings (`POST /webhooks/{id}/test`) are left out of every value. Returned by `GET /webhooks/{id}` only. If the health lookup fails, every value is empty and `failing` is false.","properties":{"lastSuccessAt":{"type":"number","nullable":true,"description":"Epoch milliseconds of the newest successful delivery among the stored events, or null."},"lastFailureAt":{"type":"number","nullable":true,"description":"Epoch milliseconds of the newest failed or expired delivery among the stored events, or null."},"failed24h":{"type":"integer","description":"Events created in the last 24 hours that failed or expired."},"total24h":{"type":"integer","description":"Events created in the last 24 hours, not counting skipped events."},"failing":{"type":"boolean","description":"True when an event failed in the last 24 hours and none succeeded in that time."}},"required":["lastSuccessAt","lastFailureAt","failed24h","total24h","failing"]},"Error":{"type":"object","additionalProperties":false,"properties":{"errors":{"type":"array","items":{"type":"string"},"description":"Array of error messages"}}}}},"paths":{"/webhooks/{id}/rotate-token":{"post":{"summary":"Rotate Webhook Token","description":"Replaces the webhook's signing token with a new generated value. The response is the only place the new token is shown in full; later reads return it masked. Deliveries sent after this call use the new token, so update your endpoint's verification before you rotate, or accept both tokens while you switch over.","parameters":[{"name":"id","in":"path","description":"ID of the Webhook","required":true,"schema":{"type":"string"}}],"operationId":"rotateWebhookToken","tags":["Webhooks"],"responses":{"200":{"description":"The webhook, with the new token in full","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Webhook"}}}},"401":{"description":"Not Authorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```

## List Webhook Events

> Lists the events sent to one webhook, newest first. Events are kept for at least 30 days. Each row has every attempt with its HTTP status, duration and error, but no bodies: \`sentBody\`, \`sentHeaders\` and each attempt's \`responseBody\` are null. Read one event with \`GET /webhook-events/{id}\` to get them. Test pings are included, with event \`ping\`. Pages are cursor-based: pass the \`cursor\` from one response to get the next page; it is null on the last page.

```json
{"openapi":"3.0.0","info":{"title":"Core API","version":"v2"},"servers":[{"url":"https://openapi.paintscout.com/v2"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"WebhookEvent":{"type":"object","additionalProperties":false,"description":"One outbound event: a send of one webhook event to one webhook, with every attempt. Events are kept for at least 30 days.","properties":{"id":{"type":"string","description":"The event ID. Sent to your endpoint in the `X-PaintScout-Event-Id` header."},"webhookId":{"type":"string","description":"The webhook the event was sent to."},"webhookUrl":{"type":"string","nullable":true,"description":"The webhook URL when the event was created."},"event":{"type":"string","description":"The event type, for example `quote-sent`. A test send is `ping`."},"status":{"type":"string","enum":["pending","processing","success","failed","expired","skipped"],"description":"`pending` and `processing`: queued or being sent, retries included. `success`: your endpoint returned a 2xx. `failed`: the last attempt failed and no retry is left. `expired`: still not delivered 48 hours after it was created. `skipped`: the webhook was deleted or disabled when the event was due, so nothing was sent."},"httpStatus":{"type":"integer","nullable":true,"description":"The HTTP status of the last attempt."},"error":{"type":"string","nullable":true,"description":"Why the last attempt failed."},"retryCount":{"type":"integer","description":"Retries made so far, not counting the first attempt."},"maxRetries":{"type":"integer","description":"Most retries this event can get."},"timestamp":{"type":"number","description":"Epoch milliseconds when the event was created."},"lastAttempt":{"type":"number","nullable":true,"description":"Epoch milliseconds of the last attempt."},"nextRetry":{"type":"number","nullable":true,"description":"Epoch milliseconds of the next retry, when one is scheduled."},"documentId":{"type":"string","nullable":true,"description":"The ID of the record the event is about, for example a quote ID."},"documentType":{"type":"string","nullable":true,"description":"The type of that record, for example `quote`."},"redeliveryOf":{"type":"string","nullable":true,"description":"For a redelivery, the ID of the event it sent again."},"durationMs":{"type":"integer","nullable":true,"description":"Duration of the last attempt, in milliseconds."},"attempts":{"type":"array","description":"Every attempt, oldest first.","items":{"$ref":"#/components/schemas/WebhookEventAttempt"}},"sentBody":{"type":"string","nullable":true,"description":"The exact request body sent, up to 64 KB. Null in `GET /webhooks/{id}/events` rows, in the responses of the test and redeliver calls, and for an event that was never sent. Read the event with `GET /webhook-events/{id}` to get it."},"sentBodyTruncated":{"type":"boolean","description":"True when the body was larger than 64 KB and `sentBody` holds only its start. Such an event cannot be redelivered."},"sentHeaders":{"type":"array","nullable":true,"description":"The request headers sent, without `Authorization` and `X-PaintScout-Signature`. Null wherever `sentBody` is null.","items":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string"},"value":{"type":"string"}}}}}},"WebhookEventAttempt":{"type":"object","additionalProperties":false,"description":"One send of an event to the webhook URL.","properties":{"at":{"type":"number","description":"Epoch milliseconds when the attempt finished."},"httpStatus":{"type":"integer","nullable":true,"description":"The HTTP status your endpoint returned, or null when no response arrived."},"durationMs":{"type":"integer","nullable":true,"description":"How long the request took, in milliseconds."},"errorCode":{"type":"string","nullable":true,"description":"A network error code such as `ECONNRESET` or `ETIMEDOUT`, when the request failed."},"error":{"type":"string","nullable":true,"description":"Why the attempt failed, or null when it succeeded."},"responseBody":{"type":"string","nullable":true,"description":"The first 2 KB of your endpoint's response. Always null in `GET /webhooks/{id}/events` rows."},"responseBodyTruncated":{"type":"boolean","description":"True when the response was longer than what `responseBody` holds."},"bodyBytes":{"type":"integer","nullable":true,"description":"Size in bytes of the request body that was sent."}}},"WebhookErrorMessage":{"type":"object","additionalProperties":false,"properties":{"message":{"type":"string","description":"Why the request was refused or failed."}},"required":["message"]},"Error":{"type":"object","additionalProperties":false,"properties":{"errors":{"type":"array","items":{"type":"string"},"description":"Array of error messages"}}}}},"paths":{"/webhooks/{id}/events":{"get":{"summary":"List Webhook Events","operationId":"listWebhookEvents","description":"Lists the events sent to one webhook, newest first. Events are kept for at least 30 days. Each row has every attempt with its HTTP status, duration and error, but no bodies: `sentBody`, `sentHeaders` and each attempt's `responseBody` are null. Read one event with `GET /webhook-events/{id}` to get them. Test pings are included, with event `ping`. Pages are cursor-based: pass the `cursor` from one response to get the next page; it is null on the last page.","tags":["Webhooks"],"parameters":[{"name":"id","in":"path","description":"ID of the Webhook","required":true,"schema":{"type":"string"}},{"name":"status","in":"query","description":"Only events with this status.","schema":{"type":"string","enum":["pending","processing","success","failed","expired","skipped"]}},{"name":"event","in":"query","description":"Only events of this type, for example `quote-sent` or `ping`.","schema":{"type":"string"}},{"name":"from","in":"query","description":"Only events created at or after this time, in epoch milliseconds.","schema":{"type":"integer","format":"int64"}},{"name":"to","in":"query","description":"Only events created at or before this time, in epoch milliseconds.","schema":{"type":"integer","format":"int64"}},{"name":"cursor","in":"query","description":"The `cursor` from the previous page. Omit it for the first page.","schema":{"type":"string"}},{"name":"limit","in":"query","description":"Events per page (1-100). Defaults to 25.","schema":{"type":"integer","format":"int32","minimum":1,"maximum":100}}],"responses":{"200":{"description":"A page of events","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"rows":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEvent"}},"cursor":{"type":"string","nullable":true,"description":"Pass as `cursor` to get the next page. Null on the last page."}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookErrorMessage"}}}},"401":{"description":"Not Authorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookErrorMessage"}}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```

## Send Test Webhook

> Sends a \`ping\` event to the webhook now and waits up to 10 seconds for the answer. It is signed like a real delivery and has the same headers. The body is \`{"eventType":"ping","timestamp":"\<ISO 8601>","companyId":"\<id>","webhookId":"\<id>"}\`. The ping is sent even when the webhook is disabled, and is never retried. It is recorded as an event, so it shows in \`GET /webhooks/{id}/events\`, but it does not count toward the webhook's \`health\`. The response is 200 whenever the send ran; \`status\` says whether your endpoint accepted it. At most 30 test sends an hour per company; more return 429.

```json
{"openapi":"3.0.0","info":{"title":"Core API","version":"v2"},"servers":[{"url":"https://openapi.paintscout.com/v2"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"WebhookTestResult":{"type":"object","additionalProperties":false,"properties":{"event":{"$ref":"#/components/schemas/WebhookEvent"},"status":{"type":"string","enum":["success","failed"],"description":"`success` when your endpoint returned a 2xx."},"durationMs":{"type":"integer","description":"How long the request took, in milliseconds."},"httpStatus":{"type":"integer","nullable":true,"description":"The HTTP status your endpoint returned, or null when no response arrived."},"responseBody":{"type":"string","nullable":true,"description":"The first 2 KB of your endpoint's response."},"responseBodyTruncated":{"type":"boolean"},"error":{"type":"string","nullable":true,"description":"Why the send failed, or null when it succeeded."}},"required":["event","status","durationMs","httpStatus","responseBody","responseBodyTruncated","error"]},"WebhookEvent":{"type":"object","additionalProperties":false,"description":"One outbound event: a send of one webhook event to one webhook, with every attempt. Events are kept for at least 30 days.","properties":{"id":{"type":"string","description":"The event ID. Sent to your endpoint in the `X-PaintScout-Event-Id` header."},"webhookId":{"type":"string","description":"The webhook the event was sent to."},"webhookUrl":{"type":"string","nullable":true,"description":"The webhook URL when the event was created."},"event":{"type":"string","description":"The event type, for example `quote-sent`. A test send is `ping`."},"status":{"type":"string","enum":["pending","processing","success","failed","expired","skipped"],"description":"`pending` and `processing`: queued or being sent, retries included. `success`: your endpoint returned a 2xx. `failed`: the last attempt failed and no retry is left. `expired`: still not delivered 48 hours after it was created. `skipped`: the webhook was deleted or disabled when the event was due, so nothing was sent."},"httpStatus":{"type":"integer","nullable":true,"description":"The HTTP status of the last attempt."},"error":{"type":"string","nullable":true,"description":"Why the last attempt failed."},"retryCount":{"type":"integer","description":"Retries made so far, not counting the first attempt."},"maxRetries":{"type":"integer","description":"Most retries this event can get."},"timestamp":{"type":"number","description":"Epoch milliseconds when the event was created."},"lastAttempt":{"type":"number","nullable":true,"description":"Epoch milliseconds of the last attempt."},"nextRetry":{"type":"number","nullable":true,"description":"Epoch milliseconds of the next retry, when one is scheduled."},"documentId":{"type":"string","nullable":true,"description":"The ID of the record the event is about, for example a quote ID."},"documentType":{"type":"string","nullable":true,"description":"The type of that record, for example `quote`."},"redeliveryOf":{"type":"string","nullable":true,"description":"For a redelivery, the ID of the event it sent again."},"durationMs":{"type":"integer","nullable":true,"description":"Duration of the last attempt, in milliseconds."},"attempts":{"type":"array","description":"Every attempt, oldest first.","items":{"$ref":"#/components/schemas/WebhookEventAttempt"}},"sentBody":{"type":"string","nullable":true,"description":"The exact request body sent, up to 64 KB. Null in `GET /webhooks/{id}/events` rows, in the responses of the test and redeliver calls, and for an event that was never sent. Read the event with `GET /webhook-events/{id}` to get it."},"sentBodyTruncated":{"type":"boolean","description":"True when the body was larger than 64 KB and `sentBody` holds only its start. Such an event cannot be redelivered."},"sentHeaders":{"type":"array","nullable":true,"description":"The request headers sent, without `Authorization` and `X-PaintScout-Signature`. Null wherever `sentBody` is null.","items":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string"},"value":{"type":"string"}}}}}},"WebhookEventAttempt":{"type":"object","additionalProperties":false,"description":"One send of an event to the webhook URL.","properties":{"at":{"type":"number","description":"Epoch milliseconds when the attempt finished."},"httpStatus":{"type":"integer","nullable":true,"description":"The HTTP status your endpoint returned, or null when no response arrived."},"durationMs":{"type":"integer","nullable":true,"description":"How long the request took, in milliseconds."},"errorCode":{"type":"string","nullable":true,"description":"A network error code such as `ECONNRESET` or `ETIMEDOUT`, when the request failed."},"error":{"type":"string","nullable":true,"description":"Why the attempt failed, or null when it succeeded."},"responseBody":{"type":"string","nullable":true,"description":"The first 2 KB of your endpoint's response. Always null in `GET /webhooks/{id}/events` rows."},"responseBodyTruncated":{"type":"boolean","description":"True when the response was longer than what `responseBody` holds."},"bodyBytes":{"type":"integer","nullable":true,"description":"Size in bytes of the request body that was sent."}}},"WebhookErrorMessage":{"type":"object","additionalProperties":false,"properties":{"message":{"type":"string","description":"Why the request was refused or failed."}},"required":["message"]},"Error":{"type":"object","additionalProperties":false,"properties":{"errors":{"type":"array","items":{"type":"string"},"description":"Array of error messages"}}}}},"paths":{"/webhooks/{id}/test":{"post":{"summary":"Send Test Webhook","operationId":"sendTestWebhook","description":"Sends a `ping` event to the webhook now and waits up to 10 seconds for the answer. It is signed like a real delivery and has the same headers. The body is `{\"eventType\":\"ping\",\"timestamp\":\"<ISO 8601>\",\"companyId\":\"<id>\",\"webhookId\":\"<id>\"}`. The ping is sent even when the webhook is disabled, and is never retried. It is recorded as an event, so it shows in `GET /webhooks/{id}/events`, but it does not count toward the webhook's `health`. The response is 200 whenever the send ran; `status` says whether your endpoint accepted it. At most 30 test sends an hour per company; more return 429.","tags":["Webhooks"],"parameters":[{"name":"id","in":"path","description":"ID of the Webhook","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The result of the send","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookTestResult"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookErrorMessage"}}}},"401":{"description":"Not Authorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookErrorMessage"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookErrorMessage"}}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```

## Retrieve Webhook Event

> Returns one outbound event with every attempt, the exact body and headers sent (without \`Authorization\` and \`X-PaintScout-Signature\`), and the first 2 KB of each response. Events are kept for at least 30 days.

```json
{"openapi":"3.0.0","info":{"title":"Core API","version":"v2"},"servers":[{"url":"https://openapi.paintscout.com/v2"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"WebhookEvent":{"type":"object","additionalProperties":false,"description":"One outbound event: a send of one webhook event to one webhook, with every attempt. Events are kept for at least 30 days.","properties":{"id":{"type":"string","description":"The event ID. Sent to your endpoint in the `X-PaintScout-Event-Id` header."},"webhookId":{"type":"string","description":"The webhook the event was sent to."},"webhookUrl":{"type":"string","nullable":true,"description":"The webhook URL when the event was created."},"event":{"type":"string","description":"The event type, for example `quote-sent`. A test send is `ping`."},"status":{"type":"string","enum":["pending","processing","success","failed","expired","skipped"],"description":"`pending` and `processing`: queued or being sent, retries included. `success`: your endpoint returned a 2xx. `failed`: the last attempt failed and no retry is left. `expired`: still not delivered 48 hours after it was created. `skipped`: the webhook was deleted or disabled when the event was due, so nothing was sent."},"httpStatus":{"type":"integer","nullable":true,"description":"The HTTP status of the last attempt."},"error":{"type":"string","nullable":true,"description":"Why the last attempt failed."},"retryCount":{"type":"integer","description":"Retries made so far, not counting the first attempt."},"maxRetries":{"type":"integer","description":"Most retries this event can get."},"timestamp":{"type":"number","description":"Epoch milliseconds when the event was created."},"lastAttempt":{"type":"number","nullable":true,"description":"Epoch milliseconds of the last attempt."},"nextRetry":{"type":"number","nullable":true,"description":"Epoch milliseconds of the next retry, when one is scheduled."},"documentId":{"type":"string","nullable":true,"description":"The ID of the record the event is about, for example a quote ID."},"documentType":{"type":"string","nullable":true,"description":"The type of that record, for example `quote`."},"redeliveryOf":{"type":"string","nullable":true,"description":"For a redelivery, the ID of the event it sent again."},"durationMs":{"type":"integer","nullable":true,"description":"Duration of the last attempt, in milliseconds."},"attempts":{"type":"array","description":"Every attempt, oldest first.","items":{"$ref":"#/components/schemas/WebhookEventAttempt"}},"sentBody":{"type":"string","nullable":true,"description":"The exact request body sent, up to 64 KB. Null in `GET /webhooks/{id}/events` rows, in the responses of the test and redeliver calls, and for an event that was never sent. Read the event with `GET /webhook-events/{id}` to get it."},"sentBodyTruncated":{"type":"boolean","description":"True when the body was larger than 64 KB and `sentBody` holds only its start. Such an event cannot be redelivered."},"sentHeaders":{"type":"array","nullable":true,"description":"The request headers sent, without `Authorization` and `X-PaintScout-Signature`. Null wherever `sentBody` is null.","items":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string"},"value":{"type":"string"}}}}}},"WebhookEventAttempt":{"type":"object","additionalProperties":false,"description":"One send of an event to the webhook URL.","properties":{"at":{"type":"number","description":"Epoch milliseconds when the attempt finished."},"httpStatus":{"type":"integer","nullable":true,"description":"The HTTP status your endpoint returned, or null when no response arrived."},"durationMs":{"type":"integer","nullable":true,"description":"How long the request took, in milliseconds."},"errorCode":{"type":"string","nullable":true,"description":"A network error code such as `ECONNRESET` or `ETIMEDOUT`, when the request failed."},"error":{"type":"string","nullable":true,"description":"Why the attempt failed, or null when it succeeded."},"responseBody":{"type":"string","nullable":true,"description":"The first 2 KB of your endpoint's response. Always null in `GET /webhooks/{id}/events` rows."},"responseBodyTruncated":{"type":"boolean","description":"True when the response was longer than what `responseBody` holds."},"bodyBytes":{"type":"integer","nullable":true,"description":"Size in bytes of the request body that was sent."}}},"Error":{"type":"object","additionalProperties":false,"properties":{"errors":{"type":"array","items":{"type":"string"},"description":"Array of error messages"}}},"WebhookErrorMessage":{"type":"object","additionalProperties":false,"properties":{"message":{"type":"string","description":"Why the request was refused or failed."}},"required":["message"]}}},"paths":{"/webhook-events/{id}":{"get":{"summary":"Retrieve Webhook Event","operationId":"getWebhookEvent","description":"Returns one outbound event with every attempt, the exact body and headers sent (without `Authorization` and `X-PaintScout-Signature`), and the first 2 KB of each response. Events are kept for at least 30 days.","tags":["Webhooks"],"parameters":[{"name":"id","in":"path","description":"ID of the event, from `GET /webhooks/{id}/events` or the `X-PaintScout-Event-Id` header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The event","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}}},"401":{"description":"Not Authorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookErrorMessage"}}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```

## Redeliver Webhook Event

> Sends an event again. This creates a new event, with a new ID, linked to the original by \`redeliveryOf\`, and queues it at once with the usual retries. The body is the exact body first sent; the timestamp and signature headers are new. Only a \`success\`, \`failed\` or \`expired\` event can be redelivered, and only when its body was stored in full, the webhook still exists and is enabled. Test pings cannot be redelivered. Each event can be redelivered once a minute, and each company can redeliver 30 events an hour; more return 429.

```json
{"openapi":"3.0.0","info":{"title":"Core API","version":"v2"},"servers":[{"url":"https://openapi.paintscout.com/v2"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"WebhookEvent":{"type":"object","additionalProperties":false,"description":"One outbound event: a send of one webhook event to one webhook, with every attempt. Events are kept for at least 30 days.","properties":{"id":{"type":"string","description":"The event ID. Sent to your endpoint in the `X-PaintScout-Event-Id` header."},"webhookId":{"type":"string","description":"The webhook the event was sent to."},"webhookUrl":{"type":"string","nullable":true,"description":"The webhook URL when the event was created."},"event":{"type":"string","description":"The event type, for example `quote-sent`. A test send is `ping`."},"status":{"type":"string","enum":["pending","processing","success","failed","expired","skipped"],"description":"`pending` and `processing`: queued or being sent, retries included. `success`: your endpoint returned a 2xx. `failed`: the last attempt failed and no retry is left. `expired`: still not delivered 48 hours after it was created. `skipped`: the webhook was deleted or disabled when the event was due, so nothing was sent."},"httpStatus":{"type":"integer","nullable":true,"description":"The HTTP status of the last attempt."},"error":{"type":"string","nullable":true,"description":"Why the last attempt failed."},"retryCount":{"type":"integer","description":"Retries made so far, not counting the first attempt."},"maxRetries":{"type":"integer","description":"Most retries this event can get."},"timestamp":{"type":"number","description":"Epoch milliseconds when the event was created."},"lastAttempt":{"type":"number","nullable":true,"description":"Epoch milliseconds of the last attempt."},"nextRetry":{"type":"number","nullable":true,"description":"Epoch milliseconds of the next retry, when one is scheduled."},"documentId":{"type":"string","nullable":true,"description":"The ID of the record the event is about, for example a quote ID."},"documentType":{"type":"string","nullable":true,"description":"The type of that record, for example `quote`."},"redeliveryOf":{"type":"string","nullable":true,"description":"For a redelivery, the ID of the event it sent again."},"durationMs":{"type":"integer","nullable":true,"description":"Duration of the last attempt, in milliseconds."},"attempts":{"type":"array","description":"Every attempt, oldest first.","items":{"$ref":"#/components/schemas/WebhookEventAttempt"}},"sentBody":{"type":"string","nullable":true,"description":"The exact request body sent, up to 64 KB. Null in `GET /webhooks/{id}/events` rows, in the responses of the test and redeliver calls, and for an event that was never sent. Read the event with `GET /webhook-events/{id}` to get it."},"sentBodyTruncated":{"type":"boolean","description":"True when the body was larger than 64 KB and `sentBody` holds only its start. Such an event cannot be redelivered."},"sentHeaders":{"type":"array","nullable":true,"description":"The request headers sent, without `Authorization` and `X-PaintScout-Signature`. Null wherever `sentBody` is null.","items":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string"},"value":{"type":"string"}}}}}},"WebhookEventAttempt":{"type":"object","additionalProperties":false,"description":"One send of an event to the webhook URL.","properties":{"at":{"type":"number","description":"Epoch milliseconds when the attempt finished."},"httpStatus":{"type":"integer","nullable":true,"description":"The HTTP status your endpoint returned, or null when no response arrived."},"durationMs":{"type":"integer","nullable":true,"description":"How long the request took, in milliseconds."},"errorCode":{"type":"string","nullable":true,"description":"A network error code such as `ECONNRESET` or `ETIMEDOUT`, when the request failed."},"error":{"type":"string","nullable":true,"description":"Why the attempt failed, or null when it succeeded."},"responseBody":{"type":"string","nullable":true,"description":"The first 2 KB of your endpoint's response. Always null in `GET /webhooks/{id}/events` rows."},"responseBodyTruncated":{"type":"boolean","description":"True when the response was longer than what `responseBody` holds."},"bodyBytes":{"type":"integer","nullable":true,"description":"Size in bytes of the request body that was sent."}}},"WebhookErrorMessage":{"type":"object","additionalProperties":false,"properties":{"message":{"type":"string","description":"Why the request was refused or failed."}},"required":["message"]},"Error":{"type":"object","additionalProperties":false,"properties":{"errors":{"type":"array","items":{"type":"string"},"description":"Array of error messages"}}}}},"paths":{"/webhook-events/{id}/redeliver":{"post":{"summary":"Redeliver Webhook Event","operationId":"redeliverWebhookEvent","description":"Sends an event again. This creates a new event, with a new ID, linked to the original by `redeliveryOf`, and queues it at once with the usual retries. The body is the exact body first sent; the timestamp and signature headers are new. Only a `success`, `failed` or `expired` event can be redelivered, and only when its body was stored in full, the webhook still exists and is enabled. Test pings cannot be redelivered. Each event can be redelivered once a minute, and each company can redeliver 30 events an hour; more return 429.","tags":["Webhooks"],"parameters":[{"name":"id","in":"path","description":"ID of the event to send again","required":true,"schema":{"type":"string"}}],"responses":{"202":{"description":"The new event, queued with status `pending`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookErrorMessage"}}}},"401":{"description":"Not Authorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookErrorMessage"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookErrorMessage"}}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://help.paintscout.com/developers/webhooks.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
