Custom Apps

Build your own integrations to receive Instructionly checkpoint notifications in your backend, mobile app, or automation tools.

Overview

Instructionly can send webhook notifications to any HTTPS endpoint you control. This allows you to build custom integrations for:

• Your own backend services
• Mobile app push notifications
• Automation platforms (Zapier, Make, n8n)
• Custom dashboards and monitoring tools
• Email services or SMS gateways

Endpoint Requirements

Your webhook endpoint must:

• Accept POST requests
• Use HTTPS (HTTP is not supported)
• Return a 2xx status code within 10 seconds
• Accept application/json content type

Payload Format

Instructionly sends a JSON payload with the following structure:

{
  "event": "checkpoint_notification",
  "type": "completion",
  "text": "Task completed: Refactored authentication module",
  "content": "Task completed: Refactored authentication module",
  "sessionId": "abc-123",
  "timestamp": "2025-01-15T10:30:00.000Z"
}

Fields

Notification Types

• completion — The AI agent has completed a task successfully
• attention_needed — The AI agent needs your input to proceed

Example: Node.js Server

Here's a simple Express server that receives webhook notifications:

const express = require('express');
const app = express();

app.use(express.json());

app.post('/webhook/instructionly', (req, res) => {
  const { event, type, text, sessionId, timestamp } = req.body;

  console.log(`[${timestamp}] ${type}: ${text}`);

  // Handle different notification types
  if (type === 'completion') {
    // Task completed - maybe send a push notification
    notifyUser('Task Complete', text);
  } else if (type === 'attention_needed') {
    // AI needs input - maybe send an urgent notification
    notifyUser('Action Required', text, { urgent: true });
  }

  // Always respond with 2xx status
  res.status(200).json({ received: true });
});

app.listen(3000, () => {
  console.log('Webhook server running on port 3000');
});

Example: Python Server

Here's the same example using Flask:

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/webhook/instructionly', methods=['POST'])
def handle_webhook():
    data = request.get_json()

    event = data.get('event')
    notification_type = data.get('type')
    text = data.get('text')
    session_id = data.get('sessionId')
    timestamp = data.get('timestamp')

    print(f"[{timestamp}] {notification_type}: {text}")

    # Handle different notification types
    if notification_type == 'completion':
        notify_user('Task Complete', text)
    elif notification_type == 'attention_needed':
        notify_user('Action Required', text, urgent=True)

    return jsonify({'received': True}), 200

if __name__ == '__main__':
    app.run(port=3000)

Configure Instructionly

1. Go to Settings → Webhooks in Instructionly
2. Enter your webhook URL (must be HTTPS)
3. Click Save
4. Enable Webhook under MCP Checkpoint Notifications
5. Click Send Test to verify your endpoint

Local Development

For local development, you can use a tunneling service to expose your local server:

# Using ngrok
ngrok http 3000

# Using localtunnel
npx localtunnel --port 3000

Use the generated HTTPS URL as your webhook endpoint in Instructionly.

Security Best Practices

• Validate the payload — Check that required fields are present and have expected types
• Use HTTPS — Never expose webhook endpoints over HTTP
• Respond quickly — Return a 2xx status within 10 seconds to avoid timeouts
• Process asynchronously — If your handler does heavy work, queue it and respond immediately
• Log requests — Keep logs for debugging and monitoring

Troubleshooting

• Not receiving webhooks: Ensure your endpoint is publicly accessible and returns a 2xx status code
• Timeout errors: Your endpoint must respond within 10 seconds. Move heavy processing to a background job
• SSL errors: Make sure your SSL certificate is valid and not self-signed
• Test works but real notifications don't: Verify "Webhook" is enabled under MCP Checkpoint Notifications