Getting Started


Welcome to the HostedHooks Tasks feature! This guide will walk you through creating and managing tasks via our API. These tasks are designed to handle background jobs efficiently, allowing you to schedule and process crucial operations for your application.


  • An active account on HostedHooks.

  • API Key for authentication (found here).

  • Basic knowledge of API requests (e.g., using curl).

Step 1: Understanding the Task Object

  • event_type: A string to label your task. Must match your webhook endpoints in the dashboard.

  • scheduled_run_time: An optional ISO8601 timestamp to schedule tasks. Leave blank for immediate execution.

  • data: A JSON blob containing data for your task. This data is sent back to your application upon task completion. For example this could be the first name and email of a user that you need to send an email to.

Step 2: Setting Up Your Environment

  • Ensure you have curl installed, or use any API client of your choice.

  • Have your HostedHooks API key at hand for authorization.

Step 3: Creating a Task

  1. Construct your API request:

    • URL: POST

      • The app_uuid is the ID of an app within your HostedHooks instance.

    • Headers:

      • Authorization: Bearer YOUR_API_KEY

      • Content-Type: application/json

    • Data: A JSON object with event_type (required), scheduled_run_time (optional), and data (required).

  2. Use the following curl command template:

curl -XPOST \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H "Content-type: application/json" \
  -d '{
    "event_type": "your.event.type",
    "scheduled_run_time": "YOUR_SCHEDULED_TIME", // Optional
    "data": {
      // Your JSON payload
  }' ''
  1. Replace YOUR_API_KEY, your.event.type, YOUR_SCHEDULED_TIME, and the JSON payload data with your specific details.

Step 4: Handling Responses

  • Upon successful task creation, the API returns a JSON response with details like task ID, event type, status, and more.

  • Example response:

  "id": "unique-task-id",
  "event_type": "your.event.type",
  "status": null,
  "scheduled_run_time": "YOUR_SCHEDULED_TIME",
  "endpoint_id": null,
  "created_at": "timestamp",
  "data": {
    // Your JSON payload

Step 5: Monitoring and Debugging

  • Check the status of your tasks in the HostedHooks dashboard or via the API

  • Use the task ID from the response for any troubleshooting or support requests.

Additional Tips

  • Ensure your event_type matches exactly with what's configured in your dashboard.

  • For scheduled tasks, verify the timezone and format of your scheduled_run_time.


You're now ready to integrate HostedHooks Tasks into your application. For any additional questions or feedback, please reach out to our support team.

Last updated