Applications

Applications represent your customers or distinct products within your organization. Each application has its own set of endpoints, event types, and webhook jobs.

The Application Object

{
  "id": "app_2Zy3X8qP9rK5mN1vB",
  "name": "Production API",
  "uid": "production-api",
  "metadata": {
    "customer_id": "cust_123",
    "environment": "production"
  },
  "endpoints_count": 5,
  "webhook_jobs_count": 1247,
  "success_rate": 99.8,
  "created_at": "2026-01-15T10:30:00Z",
  "updated_at": "2026-01-20T15:30:00Z"
}

Attribute	Type	Description
`id`	string	Unique identifier (KSUID format)
`name`	string	Human-readable application name
`uid`	string	Optional unique identifier (alphanumeric + dashes)
`metadata`	object	Custom key-value pairs for your use
`endpoints_count`	integer	Number of endpoints in this application
`webhook_jobs_count`	integer	Total webhook jobs sent
`success_rate`	float	Delivery success rate (0-100)

Multi-tenant pattern: Create one application per customer to keep their webhooks isolated. Use the uid field to store your customer's ID for easy lookups.

Create Application

Create a new application to represent a customer or product. Applications are scoped to your organization.

POST /v1/applications

Request Body

{
  "name": "Acme Corp Production",
  "uid": "acme-prod",
  "metadata": {
    "customer_id": "cust_abc123",
    "plan": "enterprise",
    "support_email": "webhooks@acme.com"
  }
}

Parameter	Required	Description
`name`	Yes	Application name (max 255 characters)
`uid`	No	Custom identifier (alphanumeric + dashes/underscores)
`metadata`	No	Custom metadata object

Response

{
  "id": "app_2Zy3X8qP9rK5mN1vB",
  "name": "Acme Corp Production",
  "uid": "acme-prod",
  "metadata": {
    "customer_id": "cust_abc123",
    "plan": "enterprise",
    "support_email": "webhooks@acme.com"
  },
  "endpoints_count": 0,
  "webhook_jobs_count": 0,
  "success_rate": 100,
  "created_at": "2026-01-20T15:30:00Z",
  "updated_at": "2026-01-20T15:30:00Z"
}

Code Examples

Node.js

const response = await fetch('https://api.hookmesh.com/v1/applications', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.HOOKMESH_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Acme Corp Production',
    uid: 'acme-prod',
    metadata: {
      customer_id: 'cust_abc123',
      plan: 'enterprise'
    }
  })
});

const application = await response.json();
console.log('Application created:', application.id);

Python

import requests
import os

response = requests.post(
    'https://api.hookmesh.com/v1/applications',
    headers={'Authorization': f'Bearer {os.environ.get("HOOKMESH_API_KEY")}'},
    json={
        'name': 'Acme Corp Production',
        'uid': 'acme-prod',
        'metadata': {
            'customer_id': 'cust_abc123',
            'plan': 'enterprise'
        }
    }
)

application = response.json()
print(f'Application created: {application["id"]}')

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
    "os"
)

func main() {
    payload := map[string]interface{}{
        "name": "Acme Corp Production",
        "uid":  "acme-prod",
        "metadata": map[string]string{
            "customer_id": "cust_abc123",
            "plan":        "enterprise",
        },
    }

    body, _ := json.Marshal(payload)
    req, _ := http.NewRequest("POST",
        "https://api.hookmesh.com/v1/applications",
        bytes.NewBuffer(body))

    req.Header.Set("Authorization", "Bearer "+os.Getenv("HOOKMESH_API_KEY"))
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()

    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)
    fmt.Printf("Application created: %s\n", result["id"])
}

PHP

<?php

$ch = curl_init('https://api.hookmesh.com/v1/applications');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . getenv('HOOKMESH_API_KEY'),
    'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'name' => 'Acme Corp Production',
    'uid' => 'acme-prod',
    'metadata' => [
        'customer_id' => 'cust_abc123',
        'plan' => 'enterprise',
    ],
]));

$response = curl_exec($ch);
$application = json_decode($response, true);
echo "Application created: {$application['id']}\n";

curl_close($ch);

List Applications

Retrieve all applications in your organization with statistics.

GET /v1/applications

Query Parameters

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`per_page`	integer	Items per page (default: 25, max: 100)
`search`	string	Search by name or uid

Response

{
  "data": [
    {
      "id": "app_2Zy3X8qP9rK5mN1vB",
      "name": "Acme Corp Production",
      "uid": "acme-prod",
      "endpoints_count": 5,
      "webhook_jobs_count": 1247,
      "success_rate": 99.8,
      "created_at": "2026-01-15T10:30:00Z"
    },
    {
      "id": "app_3Az4Y9rQ0sL6nO2wC",
      "name": "Beta Testing",
      "uid": "beta-test",
      "endpoints_count": 2,
      "webhook_jobs_count": 45,
      "success_rate": 100,
      "created_at": "2026-01-18T14:20:00Z"
    }
  ],
  "pagination": {
    "total": 2,
    "page": 1,
    "per_page": 25,
    "total_pages": 1
  }
}

Retrieve Application

Get detailed information about a specific application including endpoints and recent webhook jobs.

GET /v1/applications/{application_id}

Response

{
  "id": "app_2Zy3X8qP9rK5mN1vB",
  "name": "Acme Corp Production",
  "uid": "acme-prod",
  "metadata": {
    "customer_id": "cust_abc123",
    "plan": "enterprise"
  },
  "endpoints_count": 5,
  "webhook_jobs_count": 1247,
  "success_rate": 99.8,
  "created_at": "2026-01-15T10:30:00Z",
  "updated_at": "2026-01-20T15:30:00Z",
  "endpoints": [
    {
      "id": "ep_xyz789",
      "url": "https://api.acme.com/webhooks",
      "status": "active",
      "success_rate": 99.9
    }
  ]
}

Code Examples

Node.js

const response = await fetch(
  'https://api.hookmesh.com/v1/applications/app_2Zy3X8qP9rK5mN1vB',
  {
    headers: {
      'Authorization': `Bearer ${process.env.HOOKMESH_API_KEY}`
    }
  }
);

const application = await response.json();
console.log(`${application.name} has ${application.endpoints_count} endpoints`);

Python

import requests
import os

response = requests.get(
    'https://api.hookmesh.com/v1/applications/app_2Zy3X8qP9rK5mN1vB',
    headers={'Authorization': f'Bearer {os.environ.get("HOOKMESH_API_KEY")}'}
)

application = response.json()
print(f'{application["name"]} has {application["endpoints_count"]} endpoints')

package main

import (
    "encoding/json"
    "fmt"
    "net/http"
    "os"
)

func main() {
    req, _ := http.NewRequest("GET",
        "https://api.hookmesh.com/v1/applications/app_2Zy3X8qP9rK5mN1vB",
        nil)

    req.Header.Set("Authorization", "Bearer "+os.Getenv("HOOKMESH_API_KEY"))

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    var application map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&application)
    fmt.Printf("%s has %.0f endpoints\n",
        application["name"], application["endpoints_count"])
}

PHP

<?php

$ch = curl_init('https://api.hookmesh.com/v1/applications/app_2Zy3X8qP9rK5mN1vB');

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('HOOKMESH_API_KEY')
    ]
]);

$response = curl_exec($ch);
$application = json_decode($response, true);

echo "{$application['name']} has {$application['endpoints_count']} endpoints\n";

curl_close($ch);

Update Application

Update an application's name, uid, or metadata. All fields are optional.

PATCH /v1/applications/{application_id}

Request Body

{
  "name": "Acme Corp Staging",
  "metadata": {
    "customer_id": "cust_abc123",
    "plan": "enterprise",
    "environment": "staging"
  }
}

Response

{
  "id": "app_2Zy3X8qP9rK5mN1vB",
  "name": "Acme Corp Staging",
  "uid": "acme-prod",
  "metadata": {
    "customer_id": "cust_abc123",
    "plan": "enterprise",
    "environment": "staging"
  },
  "updated_at": "2026-01-20T16:45:00Z"
}

Delete Application

Soft delete an application. All associated endpoints and webhook jobs are also deleted (soft delete).

DELETE /v1/applications/{application_id}

Warning: Deleting an application will also delete all its endpoints and stop all webhook deliveries. This action cannot be undone.

Response

{
  "id": "app_2Zy3X8qP9rK5mN1vB",
  "deleted": true,
  "deleted_at": "2026-01-20T16:50:00Z"
}

Lookup by UID

Find an application by your custom uid instead of the Hook Mesh ID.

GET /v1/applications/by-uid/{uid}

Example

// Instead of using Hook Mesh's ID:
const app = await getApplication('app_2Zy3X8qP9rK5mN1vB');

// Use your own customer ID:
const app = await fetch(
  'https://api.hookmesh.com/v1/applications/by-uid/acme-prod',
  { headers: { 'Authorization': `Bearer ${apiKey}` } }
).then(r => r.json());

Best practice: Set uid to your customer's ID when creating applications. This makes it easy to look up applications without storing Hook Mesh's internal IDs.

Common Patterns

Multi-tenant Setup

When a new customer signs up for your service, create an application for them:

async function onCustomerSignup(customer) {
  // Create Hook Mesh application for this customer
  const application = await fetch('https://api.hookmesh.com/v1/applications', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.HOOKMESH_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: customer.companyName,
      uid: customer.id, // Use your customer ID
      metadata: {
        customer_id: customer.id,
        plan: customer.plan,
        support_email: customer.email
      }
    })
  }).then(r => r.json());

  // Store the application ID with your customer
  await db.customers.update(customer.id, {
    hookmesh_application_id: application.id
  });

  return application;
}

Metadata Usage

Store any custom data you need in metadata for easy filtering and reference:

{
  "metadata": {
    "customer_id": "cust_123",
    "plan": "enterprise",
    "region": "us-west-2",
    "account_manager": "sarah@yourcompany.com",
    "created_by": "admin@yourcompany.com",
    "billing_id": "stripe_cust_xyz",
    "internal_notes": "High-volume customer, priority support"
  }
}

Next Steps

Create endpoints for your application to receive webhooks
Define event types that your application will send
Send webhook jobs to your application's endpoints