Webhooks API
Create, list, delete and test outgoing webhook endpoints.
Preview
Preview: the API and MCP server are in private beta; details may change.
This page covers managing webhook endpoints. For the full event list, payload shape and how to verify the IMMA-Signature header, see Webhooks.
Required scope: webhooks:write.
Endpoints
| Method | Path | Description |
|---|---|---|
| GET | /webhooks | List webhook endpoints |
| POST | /webhooks | Create a webhook endpoint |
| DELETE | /webhooks/{id} | Remove a webhook endpoint |
| POST | /webhooks/{id}/test | Send a synthetic event to verify signature handling |
Request parameters
| Name | Type | Required | Description |
|---|---|---|---|
url | string | Yes | Must be a public https URL; private IPs and localhost are rejected |
events | array of strings | Yes | Any of the event types listed in Webhooks |
curl -X POST https://api.getimma.com/v1/webhooks \
-H "Authorization: Bearer imma_live_xxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"url": "https://customer.example/webhook",
"events": ["post.published", "post.failed"]
}'Response:
{
"id": "wh_01J...",
"url": "https://customer.example/webhook",
"events": ["post.published", "post.failed"],
"secret": "whsec_5f2b...",
"active": true
}secret is shown once, at creation. Store it; it is needed to verify IMMA-Signature and cannot be viewed again (generate a new endpoint if it is lost).
Test an endpoint
curl -X POST https://api.getimma.com/v1/webhooks/wh_01J.../test \
-H "Authorization: Bearer imma_live_xxxxxxxxxxxxxxxxxxxx"Sends a synthetic event to the endpoint so you can verify signature handling before relying on it in production.
Errors
| Code | HTTP | When |
|---|---|---|
unauthorized | 401 | Missing or invalid API key |
insufficient_scope | 403 | Key lacks webhooks:write |
invalid_url | 400 | url is not a public https URL |
not_found | 404 | Endpoint does not exist, or belongs to another workspace |
See Errors for the shared error shape.
Platform notes
Webhook delivery is not platform specific; the same endpoint receives events for TikTok, Instagram, Facebook Pages and Threads posts. An endpoint that fails continuously is automatically disabled after repeated failures; see Webhooks for retry and deduplication behavior.