Developer Settings

Access Taskr’s API and configure webhooks for custom integrations. Build automated workflows, connect external systems, and extend platform functionality.

Access: Only Owners and Admins can access developer settings. See Role Definitions for details.

Overview

Developer settings provide:

Feature	Description
API Access	Authenticate external applications
Webhooks	Receive real-time event notifications
Organization ID	Your unique organization identifier
API Documentation	Reference for all endpoints

Accessing Developer Settings

Go to Settings > Developer
Or navigate directly to /settings/developer

API Access

Understanding API Keys

API keys authenticate external applications with Taskr:

Key Property	Description
Key ID	Public identifier for the key
Secret	Private token (shown once at creation)
Permissions	What the key can access
Created	When the key was generated
Last Used	Most recent API call

Creating an API Key

Go to Settings > Developer > API Keys
Click Create API Key
Enter a descriptive name (e.g., “Zapier Integration”)
Select permissions:
- Read - View data only
- Write - Create and update data
- Full Access - All operations including delete
Click Create
Copy the secret key immediately (it will not be shown again)
Store the key securely

Security warning: Treat API keys like passwords. Never expose them in client-side code, public repositories, or logs.

API Key Permissions

Permission Level	Allowed Operations
Read	GET requests only
Write	GET, POST, PUT, PATCH
Full Access	All including DELETE

Managing API Keys

Action	How To
View Keys	See all active keys with usage stats
Regenerate	Create new secret, invalidate old one
Delete	Permanently remove key
Edit Name	Update key description

To delete an API key:

Find the key in the list
Click the Actions menu
Select Delete
Confirm the deletion

Deleted keys immediately stop working. Any integrations using the key will fail.

API Authentication

Use your API key in requests: Header authentication (recommended):

Authorization: Bearer YOUR_API_KEY

Query parameter (less secure):

GET /api/customers?api_key=YOUR_API_KEY

Rate Limits

API requests are rate-limited to ensure platform stability:

Plan	Rate Limit
Starter	100 requests/minute
Professional	500 requests/minute
Business	1000 requests/minute
Enterprise	Custom limits

Rate limit headers are included in responses:

Header	Description
`X-RateLimit-Limit`	Maximum requests per window
`X-RateLimit-Remaining`	Requests left in window
`X-RateLimit-Reset`	When the window resets

Webhooks

Understanding Webhooks

Webhooks notify your systems when events occur in Taskr:

Component	Description
Endpoint URL	Your server URL that receives events
Events	Which activities trigger notifications
Payload	JSON data about the event
Signature	Verification header for security

Creating a Webhook

Go to Settings > Developer > Webhooks
Click Add Webhook
Enter your endpoint URL (must be HTTPS)
Select events to subscribe to
Click Create
Copy the signing secret for verification

Available Events

Category	Events
Customers	created, updated, deleted
Jobs	created, updated, status_changed, completed
Quotes	created, sent, approved, declined
Invoices	created, sent, paid, overdue
Assets	created, updated, deleted
Faults	created, assigned, resolved

Webhook Payload

Each webhook delivers a JSON payload:

{
  "event": "job.completed",
  "timestamp": "2025-01-15T10:30:00Z",
  "organization_id": "org_abc123",
  "data": {
    "id": "job_xyz789",
    "status": "completed",
    "completed_at": "2025-01-15T10:30:00Z"
  }
}

Verifying Webhooks

Validate incoming webhooks using the signature header:

Header	Description
`X-Taskr-Signature`	HMAC-SHA256 signature
`X-Taskr-Timestamp`	Request timestamp

Verification process:

Concatenate timestamp and raw body
Compute HMAC-SHA256 using your signing secret
Compare with the signature header
Reject if mismatch or timestamp is too old (5+ minutes)

Managing Webhooks

Action	How To
View Logs	See delivery history and responses
Test	Send a test event to your endpoint
Disable	Temporarily stop deliveries
Delete	Remove the webhook

Webhook Delivery

Status	Meaning
Success	2xx response received
Failed	Non-2xx response or timeout
Pending	Awaiting delivery attempt
Retrying	Failed, retry scheduled

Retry policy:

First retry: 1 minute
Second retry: 5 minutes
Third retry: 30 minutes
Final retry: 2 hours
After 5 failures: Webhook disabled

Testing Webhooks

Go to the webhook settings
Click Send Test Event
Select an event type
Click Send
Check your endpoint received the payload

Organization Identifiers

Finding Your IDs

Identifier	Location	Use
Organization ID	Developer settings page	API requests, webhooks
Team IDs	Team settings	Filtering API responses
User IDs	Team member details	User-specific operations

These identifiers are used in API requests to scope data access.

API Documentation

Accessing Documentation

Full API documentation is available:

Go to Settings > Developer
Click API Documentation
Browse available endpoints
View request/response examples

API Base URL

https://api.taskr.app/v1

Common Endpoints

Endpoint	Method	Description
`/customers`	GET	List customers
`/customers/{id}`	GET	Get single customer
`/jobs`	GET	List jobs
`/jobs`	POST	Create a job
`/invoices`	GET	List invoices
`/quotes`	GET	List quotes

Security Best Practices

API Key Security

Generate separate keys for each integration
Use minimum necessary permissions
Rotate keys periodically
Delete unused keys immediately
Never commit keys to version control
Use environment variables to store keys

Webhook Security

Always verify signatures
Use HTTPS endpoints only
Validate timestamp to prevent replay attacks
Log and monitor webhook deliveries
Implement idempotency for event handling

Troubleshooting

API Requests Failing

Error Code	Cause	Solution
401	Invalid or missing API key	Check key is correct
403	Insufficient permissions	Use key with correct access
404	Resource not found	Verify ID and endpoint
429	Rate limit exceeded	Reduce request frequency
500	Server error	Retry or contact support

Webhook Not Receiving Events

Verify endpoint URL is correct and accessible
Check endpoint returns 2xx status
Review webhook logs for delivery attempts
Test endpoint manually with curl or Postman
Ensure firewall allows Taskr IP addresses

Webhook Disabled

If a webhook is disabled due to failures:

Fix the underlying endpoint issue
Go to webhook settings
Click Re-enable
Send a test event to verify

Integrations - Third-party app connections
Role Definitions - Access levels
Organization Settings - Organization configuration

Back to Settings Overview | Back to Documentation Index

​Developer Settings

​Overview

​Accessing Developer Settings

​API Access

​Understanding API Keys

​Creating an API Key

​API Key Permissions

​Managing API Keys

​API Authentication

​Rate Limits

​Webhooks

​Understanding Webhooks

​Creating a Webhook

​Available Events

​Webhook Payload

​Verifying Webhooks

​Managing Webhooks

​Webhook Delivery

​Testing Webhooks

​Organization Identifiers

​Finding Your IDs

​API Documentation

​Accessing Documentation

​API Base URL

​Common Endpoints

​Security Best Practices

​API Key Security

​Webhook Security

​Troubleshooting

​API Requests Failing

​Webhook Not Receiving Events

​Webhook Disabled

​Related Documentation