Create a webhook

post

https://vision-api.truepic.{tld}/v3/webhooks

Body Params

custom_headers

object | string,null

Any custom headers to send in the webhook POST request. To send a unique request ID header, create a header with a value of {{ UUID }}. When the webhook is sent, this will be replaced with a unique UUID for each request.

enabled_events

array | string,null

The events this webhook receives. null (the default, and what every webhook created before this field existed holds) means every event.

Event names follow the webhook's configured API version. Both legacy v2 and current v3 spellings are accepted when configuring enabled_events.

is_disabled

boolean

Whether the webhook is disabled. Set this to true to stop the webhook sending POST requests, or false to enable it. To leave its disabled state unchanged, omit this field.

mutual_tls

boolean

Defaults to false

Whether to use mutual TLS when sending the webhook POST request. This is an additional security measure that requires the receiving service to present a valid TLS certificate and to verify our API server's certificate before accepting the request.

oauth_client_secret

string | null

The OAuth client_secret Vision presents when requesting an access token from oauth_config.token_url. Write-only: it is stored encrypted and is never returned by this API. To set or rotate it, provide the new secret. To remove it, set this to null. To leave it unchanged, omit this field.

oauth_config

TeamWebhookOAuthConfig | string,null

OAuth 2.0 client credentials configuration. When set, Vision obtains an access token from the configured token endpoint and presents it on the webhook request. null means the webhook is delivered without OAuth.

This is independent of the truepic-signature payload signature and of mutual TLS: any combination of the three can be used together.

secret

string | null

The secret used to authenticate webhooks. When we send webhooks to your endpoint, we add a truepic-signature header to those requests, generated with this secret. When your endpoint receives a webhook POST request, it can verify that the request was signed with this secret to confirm that it's from us. To remove the secret, set this to null. To set a new secret, provide the new secret string. To leave the secret unchanged, omit this field.

team_id

number

required

The ID of the team. Each team can have only one webhook.

url

required

The URL the webhook POST request is sent to.

vision_api_version

string

enum

Defaults to v3

The API version used to send the webhook POST request. Determines the terminology (v2 or v3) sent.

Allowed:

Responses

201Success

400The request is malformed or fails path, query, body, or lifecycle validation. Standard errors include response_code, message and api_version, and an error_code when a client can act on the specific reason. Use the x-request-id response header when reporting a failed request.

401Authentication failed, or the user/client doesn't have permission to access the requested resource.

403The user doesn't have permission to access the requested resource.

404The requested resource couldn't be found.

412A request precondition failed. Some operations also return 412 when a related resource is not found, such as an assigned member when updating an inspection. Missing required fields normally return 400. Check the operation and message for the failed precondition.

500An unexpected error occurred.