Build and Test Your First Jomioz API Integration

This guide walks you through the complete lifecycle of a Jomioz integration. By the end, you will have authenticated with the API, created your first resource, registered a webhook endpoint to receive event notifications, and verified that your integration is working end-to-end.

Use the Jomioz sandbox environment (https://sandbox.api.jomioz.com/v1) while following this guide so you can experiment freely without affecting your production data. See the Configuration guide for details on switching environments.

Authenticate

Every request to the Jomioz API requires your API key in the Authorization header. Retrieve your key from Dashboard → Settings → API Keys, then include it in all requests using the Bearer scheme.

curl https://sandbox.api.jomioz.com/v1/api/users \
  -H "Authorization: Bearer YOUR_API_KEY"

A successful response confirms your credentials are valid and returns your user list. Store your API key in an environment variable rather than hard-coding it in source files.

export JOMIOZ_API_KEY="YOUR_API_KEY"

Create a Resource

Resources are the core data objects in Jomioz. Send a POST request to /api/resources with a JSON body describing the resource you want to create.

curl -X POST https://sandbox.api.jomioz.com/v1/api/resources \
  -H "Authorization: Bearer $JOMIOZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My First Resource",
    "type": "sensor",
    "status": "active",
    "metadata": {
      "env": "sandbox",
      "owner": "your-team"
    }
  }'

Jomioz returns the newly created resource object, including its system-assigned id:

{
  "id": "res_01hx3kpq7bnf9z2t4m6vw8cde",
  "name": "My First Resource",
  "type": "sensor",
  "status": "active",
  "metadata": {
    "env": "sandbox",
    "owner": "your-team"
  },
  "created_at": "2024-06-01T12:00:00Z",
  "updated_at": "2024-06-01T12:00:00Z"
}

Save the id value — you will need it in later steps.

List Your Resources

Retrieve all resources in your workspace with a GET request to /api/resources. The response is paginated; by default it returns the 20 most recently created resources.

curl https://sandbox.api.jomioz.com/v1/api/resources \
  -H "Authorization: Bearer $JOMIOZ_API_KEY"

The response includes a data array of resource objects alongside pagination metadata:

{
  "data": [
    {
      "id": "res_01hx3kpq7bnf9z2t4m6vw8cde",
      "name": "My First Resource",
      "type": "sensor",
      "status": "active",
      "created_at": "2024-06-01T12:00:00Z"
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 20,
    "next_cursor": null
  }
}

Use the next_cursor value in subsequent requests to page through large result sets. See Advanced Usage for full pagination details.

Set Up a Webhook

Jomioz delivers real-time event notifications to your application via webhooks. Register a publicly accessible HTTPS endpoint to receive these payloads.

curl -X POST https://sandbox.api.jomioz.com/v1/api/webhooks \
  -H "Authorization: Bearer $JOMIOZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.example.com/webhooks/jomioz",
    "events": [
      "resource.created",
      "resource.updated",
      "event.fired"
    ],
    "description": "My first webhook listener"
  }'

A successful registration returns the webhook object including a secret you use to verify incoming payloads:

{
  "id": "wh_09yz7mnp2cqx5r8b3j1svt6fa",
  "url": "https://your-app.example.com/webhooks/jomioz",
  "events": ["resource.created", "resource.updated", "event.fired"],
  "secret": "whsec_YOUR_WEBHOOK_SECRET",
  "status": "active",
  "created_at": "2024-06-01T12:05:00Z"
}

Store whsec_YOUR_WEBHOOK_SECRET securely. Jomioz signs every webhook delivery with this secret so you can confirm the payload originated from Jomioz and has not been tampered with.

Trigger and Receive an Event

Post a custom event to confirm that your webhook endpoint receives deliveries correctly. Send a POST request to /api/events referencing the resource you created in Step 2.

curl -X POST https://sandbox.api.jomioz.com/v1/api/events \
  -H "Authorization: Bearer $JOMIOZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "event.fired",
    "resource_id": "res_01hx3kpq7bnf9z2t4m6vw8cde",
    "payload": {
      "message": "Hello from my first integration!"
    }
  }'

Within a few seconds your endpoint will receive a POST request with a body similar to:

{
  "id": "evt_04ab2cfr8dkj7n5p1qw9lx3ym",
  "type": "event.fired",
  "resource_id": "res_01hx3kpq7bnf9z2t4m6vw8cde",
  "payload": {
    "message": "Hello from my first integration!"
  },
  "created_at": "2024-06-01T12:10:00Z"
}

Confirm the delivery in Dashboard → Webhooks → [your webhook] → Deliveries. You will see each attempt, the HTTP status code your server returned, and the full request and response bodies.

If your endpoint is not yet publicly accessible, use a tunneling tool such as ngrok to expose a local port during development. Replace the url in your webhook registration with the tunnel URL.

Get Started

Core Concepts

Guides

Integrations

Support

Build and Test Your First Jomioz API Integration