Getting Started with the Tropic API and Webhooks – Tropic help center

API

The Tropic API empowers you to programmatically manage your software procurement and spend optimization workflows. Built on REST principles, our API provides predictable, resource-oriented URLs and uses standard HTTP methods.

All requests and responses are JSON-encoded, with conventional HTTP response codes indicating the success or failure of each operation.

NOT A DEVELOPER? Tropic seamlessly connects with leading procurement, ERP, and financial systems through our native integrations. Start optimizing your software spend, automating renewals, and managing vendors without writing a single line of code.

Managing API Keys

The API Keys & Webhooks page is designed to provide a self-service way for users with the Admin role to help setup and manage the API Keys and webhooks.

Navigate to Settings > API Keys & Webhooks

You can view the list of API Keys and webhooks in each respectable tabs.

Creating an API Key

API keys are unique identifiers used to authenticate your requests to the Tropic API. Think of them as passwords that allow our systems to verify your identity and grant appropriate access to API resources.

To generate a new API key:

Navigate to the API Keys tab
Click the Generate API Key button in the top right corner of the table
Enter a name for your API key in the dialog
Click Create
Copy your new API key immediately

Revoking an API Key

To revoke a new API key:

Click Revoke API Key in the line
Click Yes, revoke API Key in the dialog

Revoking an API key is not a reversible action, once a API key is revoked we can't set it to be active again.

Webhooks

The Webhook API enables real-time event-driven integrations with your existing systems and workflows. Built on industry-standard web protocols, our webhook system provides reliable event delivery, secure payload transmission, and easy-to-implement endpoint management. All webhook notifications are JSON-encoded, with detailed event types and comprehensive payload data to help you respond to changes instantly.

Managing Webhooks

The API Keys & Webhooks page is designed to provide a self-service way for users with the Admin role to help setup and manage the API Keys and webhooks.

Navigate to Settings > API Keys & Webhooks

You can view the list of API Keys and webhooks in each respectable tabs.

Creating a Webhook

Webhooks enable seamless integration by allowing your application to be notified about changes or actions happening in the Tropic app, such as purchase request task status changes, or new contract being created. When you create a webhook, we automatically generate a unique secret key for that webhook. This secret can be used to verify that the requests you receive are authentic and originated from our application, enhancing security and ensuring the integrity of the data being shared.

To create a new webhook:

Navigate to the Webhooks tab
Click the Add Webhook button in the top right corner of the table
Enter the required fields
Click Add Webhook
Find your webhook secret in the details panel below
To activate webhook, toggle on in the index

Verifying a Webhook

To verify that a webhook request is authentic and sent from the Tropic application, you can use the provided signature and the secret key associated with your webhook. Here’s how the verification process works:

To verify a webhook:

Recreate the Signed Payload: Combine the timestamp from the Tropic-Timestamp header and the raw request body using the format:

signed_payload = "#{timestamp}.#{payload}"

Generate the Expected Signature: Use the webhook secret and the SHA-256 HMAC algorithm to hash the signed payload:

expected_signature = OpenSSL::HMAC.hexdigest("SHA256", YOUR_WEBHOOK_SECRET, signed_payload)

Compare the Signatures: Check if the expected signature matches the signature sent in the Tropic-Signature header. If they match, the request is verified and came from the Tropic application.

Here's a snippet for performing the validation in Ruby:

timestamp = request.headers["Tropic-Timestamp"]
payload = request.body
signed_payload = "#{timestamp}.#{payload}"
expected_signature = OpenSSL::HMAC.hexdigest("SHA256", YOUR_WEBHOOK_SECRET, signed_payload)
if expected_signature == request.headers["Tropic-Signature"]   
# Request is verified
else   
# Request is not authentic
end

This process is consistent across programming languages, so developers can adapt it to their preferred stack while ensuring the security of the webhook integration.

Editing a Webhook

Webhook name, URL and resource actions can be modified at any point, however the secret will not change even if a webhook's information is updated.

To edit a new webhook:

Click the ellipsis [...] button in line.
Click Edit.
Update your information.
Click Save.

API Logs and Webhook Events

You can view API Logs and Webhook Events under Settings → API Keys & Webhooks.

API Logs: Track API activity with details like request date, method, path, status code, and error messages. Note that Payloads are not included in API Logs.

Webhook Events: View webhook event logs with timestamps and statuses. Clicking on an event lets you see the full payload for easier debugging.

Rate Limiting

The Tropic API uses rate limiting to maintain security and stability. If more than 50 requests per minute are sent, the API will return a 429 (Too Many Requests) response.

To ensure your integration continues to function as expected, we recommend implementing a retry mechanism with exponential backoff to reduce request volume when necessary.

Endpoints

The Tropic API provides various endpoints to help you manage procurement and spend workflows. Below are some commonly used examples:

Contracts:

GET /api/v1/contracts: Retrieves all contracts.
POST /api/v1/contracts: Creates a new contract.
PUT /api/v1/contracts/{contract_id}: Updates a specific contract.

Purchase Requests:

GET /api/v1/purchase_requests: Retrieves all purchase requests.
PUT /api/v1/purchase_requests/{purchase_request_id}: Updates a specific purchase request.

Comments:

GET /api/v1/purchase_requests/{purchase_request_id}/comments: Retrieves all comments for a purchase request.
POST /api/v1/purchase_requests/{purchase_request_id}/comments: Adds a comment to a purchase request.

Suppliers:

POST /api/v1/suppliers: Creates a new supplier.
GET /api/v1/suppliers/search: Searches for suppliers by name or other parameters. Provide a query parameter with letters to narrow your search results.
GET /api/v1/suppliers/{supplier_id}: Retrieves details of a specific supplier using their unique ID.
PUT /api/v1/suppliers/{supplier_id}: Updates information for an existing supplier, such as name, contact details, or custom fields.

API