V2 Webhooks (Beta)

Webhooks allow your application to receive real-time HTTP notifications when specific events occur in our system. Instead of continuously polling our APIs for updates, you can register a webhook endpoint, and we’ll automatically send a POST request with event data whenever the configured event is triggered. This enables seamless integrations, faster workflows, and efficient communication between systems.

Webhook events: In order to receive webhook event notifications, select the desired webhook events when you create your app.

Callback URL: Enter the callback URL for each event. The callback URL identifies the endpoint on your server where webhook events will be delivered via HTTP POST requests. This URL must be publicly accessible and capable of processing incoming JSON payloads. Ensure it is secured with HTTPS to protect data in transit.

HMAC key: You may generate a random HMAC key by clicking the Generate button, or manually enter a 32- to 64-character key in the HMAC Key field. Securely configure the same key in your application. HMAC stands for Hash-based Message Authentication Code. Using the HMAC key protocol adds a vital layer of security. It allows you to verify that the webhook payload genuinely originated from the ServiceTitan system and wasn’t altered in transit. By computing a hash of the payload using the shared secret (HMAC key) and comparing it with the signature sent in the request header, you can ensure both authenticity and data integrity. This helps prevent spoofed requests, tampering, and unauthorized access to sensitive event data.

Returning 2xx HTTP response code: To acknowledge successful receipt of a webhook event, your system should return an HTTP 200 OK response. This lets our servers know the event was received and processed correctly. Failing to return a 2XX status may result in retries.

Sample code to return 2XX:

  • Use the below sample code as reference to generate a 2XX response.

  • For example, when using ASP.NET Core, return Ok() or NoContent() from a controller action, or Results.Ok() or Results.NoContent() from a minimal API endpoint.

Webhooks Retry: If your system does not return an HTTP 2XX response, the ServiceTitan platform treats it as a failed delivery and will automatically retry sending the notification at intervals of 10, 30, 60, and 300 seconds.

Note: If your system is unavailable for more than 300 seconds, these events can be manually replayed through the Developer Portal. You’ll be able to view a list of failed events within a selected time period and replay them as needed. This failed events screen is currently under development and is expected to be available by the end of Fall 2025.