Building for DonutWork

This guide provides a conceptual and technical blueprint for developing third-party applications. The DonutWork framework is explicitly programming language agnostic, relying on standard HTTP/REST protocols and secure UI embedding to facilitate cross-system orchestration.

1. Application Registration

Before you begin development, you must register your application to obtain the necessary credentials for identity and platform access.

• Client ID: Your application's public identifier.
• Client Secret: A secure credential used to authorize your app to act on behalf of a company.
• Redirect URI: The URL where DonutWork will send authorization codes.

Refer to the Detailed OAuth Guide for the technical authentication handshake.

2. Capability Discovery (The Manifest)

DonutWork uses a Discovery Pattern to understand what your application is capable of. Instead of DonutWork calling your app blindly, your app must "declare" its capabilities (Actions).

Declaring Capabilities

Your application should send a PUT request to the /integrations.json endpoint. This manifest tells DonutWork which endpoints to call when a specific action is triggered (e.g., via a Workflow or the UI).

{
  "app_token": "YOUR_APP_SHARED_TOKEN",
  "capabilities": [
    {
      "name": "ping",
      "description": "Test connection health",
      "endpoint": "https://your-app.com/api/ping.json",
      "method": "GET",
      "inputs": []
    },
    {
      "name": "provision_resource",
      "description": "Create a new resource",
      "endpoint": "https://your-app.com/api/provision.json",
      "method": "POST",
      "inputs": [
        {
          "name": "resource_name",
          "type": "string",
          "required": true
        }
      ]
    }
  ]
}

• app_token: DonutWork will include this Bearer token in every Authorization header when it calls your application. This allows your app to verify that the request is coming from DonutWork.
• capabilities: An array of allowed actions, each with a defined endpoint, method, and expected inputs.

3. Communication Pattern (The Action Logic)

When a user or a generic workflow triggers an action, DonutWork acts as a Secure Proxy.

1. Trigger: DonutWork identifies the target Action (e.g., provision_resource).
2. Identification: DonutWork retrieves the endpoint and app_token from your saved manifest.
3. Execution: DonutWork sends an HTTP request to your endpoint, including the app_token in the header and the required data in the body.
4. Response: Your application processes the request and returns a standard JSON response.

4. UI Framework (The Iframe)

DonutWork embeds your application's frontend inside its own dashboard via an Iframe. To ensure a smooth user experience and maintain security, you must adhere to the following policies:

Cookie Security (SameSite=None)

Because your application is running in an Iframe context (cross-site), traditional session cookies may be blocked by modern browsers. You must configure your session cookies with:

• SameSite=None
• Secure=true

Security Headers

DonutWork allows Iframe embedding from registered applications. On your end, you should ensure your headers allow the platform to display your content. For a deep dive into signature verification, see Iframe Context & Security.

Content-Security-Policy: frame-ancestors 'self' https://hub.donutwork.com;
X-Frame-Options: ALLOW-FROM https://hub.donutwork.com

5. Event Synchronization (Webhooks)

To react to platform events in real-time (e.g., when a user pays a bill), you should register a Webhook.

1. Endpoint: Your application should provide a dedicated HTTPS URL to receive POST payloads.
2. Key Rotation: During registration, you will receive a token. Use this key to verify the X-SIGNATURE header on every incoming request.

6. Uninstall Callback (Company Data Cleanup)

When a company uninstalls your app from DonutWork, the platform sends a server-to-server callback to your configured uninstall_url.

• Method: DELETE
• Content-Type: application/x-www-form-urlencoded
• Body:
  • company_id: Company identifier to delete.
  • verify: HMAC signature computed as HMAC_SHA256(company_id, client_secret).

Example payload:

DELETE /uninstall HTTP/1.1
Content-Type: application/x-www-form-urlencoded

company_id=699ecb44790ac4eea20e9cd3&verify=7c72b2...

Verification rule on your side:

$expected = hash_hmac('sha256', $companyId, $clientSecret);
$isValid = hash_equals($expected, $verify);

Implementation requirements:

• Validate company_id and verify before deleting anything.
• Delete only tenant-scoped data for that company_id.
• Make the endpoint idempotent (repeated calls must not fail).
• Return a 2xx response only when cleanup is completed (or already completed).

If your endpoint returns non-2xx, DonutWork will treat the uninstall callback as failed and local uninstall will be blocked.

Summary Checklist

• Register App and obtain Client ID/Secret.
• Implement OAuth 2.0 to obtain Platform Access Tokens.
• Use PUT /integrations.json to declare your app's endpoints.
• Implement your API endpoints to handle requests from the DonutWork proxy.
• Configure SameSite=None and Secure cookies for your Iframe UI.
• Register Webhooks for real-time event processing.
• Implement DELETE uninstall_url with company_id + HMAC verify and tenant-safe cleanup.