Endpoints
Create Webhook
Create a webhook for post and auto-reply lifecycle events.
POST
/
api
/
v1
/
webhooks
Create webhook
curl --request POST \
--url https://mallary.ai/api/v1/webhooks \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"url": "<string>",
"events": [],
"secret": "<string>"
}
'import requests
url = "https://mallary.ai/api/v1/webhooks"
payload = {
"url": "<string>",
"events": [],
"secret": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({url: '<string>', events: [], secret: '<string>'})
};
fetch('https://mallary.ai/api/v1/webhooks', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://mallary.ai/api/v1/webhooks",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'url' => '<string>',
'events' => [
],
'secret' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://mallary.ai/api/v1/webhooks"
payload := strings.NewReader("{\n \"url\": \"<string>\",\n \"events\": [],\n \"secret\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://mallary.ai/api/v1/webhooks")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"url\": \"<string>\",\n \"events\": [],\n \"secret\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://mallary.ai/api/v1/webhooks")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"url\": \"<string>\",\n \"events\": [],\n \"secret\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"id": 123,
"url": "<string>",
"events": [
"*"
]
}Delivery body
Mallary sends a JSON body like this:{
"event": "post.published",
"event_id": "7dd724b3-e237-4b1f-9d3c-28f1932eb195",
"data": {
"batch_id": "batch_example",
"platform": "facebook",
"status": "completed"
},
"sent_at": "2026-08-08T12:00:00.000Z",
"signed_payload": "{\"event\":\"post.published\",\"event_id\":\"7dd724b3-e237-4b1f-9d3c-28f1932eb195\",\"data\":{\"batch_id\":\"batch_example\",\"platform\":\"facebook\",\"status\":\"completed\"},\"sent_at\":\"2026-08-08T12:00:00.000Z\"}"
}
X-Mallary-Payload-Signature as sha256=<hex digest>. It is the HMAC-SHA256 signature of the exact signed_payload string. Verify it before parsing or using the event.
Final failures
Subscribe topost.job_failed for a job’s final failure. This event is saved as soon as the job fails, even if other jobs in its batch are still waiting. It also works for jobs without a batch. A final failure has retries_remaining: 0 and retry_at: null.
post.failed, post.partial, and post.published keep their existing batch behavior. For prompt failure alerts, use post.job_failed. Use * to receive all events, including the job events.
Delivery retries
Mallary saves each delivery before sending it. A failed delivery gets up to five more attempts, with waits of 1 minute, 5 minutes, 30 minutes, 2 hours, and 8 hours. A validRetry-After header can extend a wait, up to 24 hours. Each HTTP attempt has a 10-second timeout. Redirects count as failed deliveries.
The body, event_id, and sent_at stay the same across retries. X-Mallary-Event-Id also contains the event ID. Your endpoint should return a 2xx response and handle each event ID once: a lost response can cause the same event to arrive again. Keep the event ID for at least seven days.
Events can arrive out of order while a delivery is being retried. Read the job’s current status before taking action on an older event.
Delivery retries send the notification again. They do not retry the social post. Deleting or disabling a webhook cancels its pending deliveries; a request already in flight may still finish.
Use delivery history to inspect each attempt and find deliveries that ran out of retries. These records start when durable delivery is enabled; earlier deliveries are not backfilled.Body
application/json
Last modified on October 19, 2026
Was this page helpful?
Create webhook
curl --request POST \
--url https://mallary.ai/api/v1/webhooks \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"url": "<string>",
"events": [],
"secret": "<string>"
}
'import requests
url = "https://mallary.ai/api/v1/webhooks"
payload = {
"url": "<string>",
"events": [],
"secret": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({url: '<string>', events: [], secret: '<string>'})
};
fetch('https://mallary.ai/api/v1/webhooks', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://mallary.ai/api/v1/webhooks",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'url' => '<string>',
'events' => [
],
'secret' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://mallary.ai/api/v1/webhooks"
payload := strings.NewReader("{\n \"url\": \"<string>\",\n \"events\": [],\n \"secret\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://mallary.ai/api/v1/webhooks")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"url\": \"<string>\",\n \"events\": [],\n \"secret\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://mallary.ai/api/v1/webhooks")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"url\": \"<string>\",\n \"events\": [],\n \"secret\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"id": 123,
"url": "<string>",
"events": [
"*"
]
}
