Webhooks
Register a public HTTPS endpoint using the customer's key. Jawib sends only events belonging to that customer to their endpoint. Your platform may use a shared URL, provided that it verifies the correct customer's signing secret before trusting the event.
Event envelope
Events include an ID, type, version, creation time, workspace identifier, customer identifier where applicable, and event-specific data. Save the event ID to prevent duplicate processing. API tokens and webhook signing secrets are independent credentials.
The endpoint-registration response returns data.secret once. Store it securely. Content-event registration also requires the corresponding read scopes: conversations:read, groups:messages:read, or groups:receipts:read.
Verify signatures
Read the original request body without re-encoding it. Reject missing, malformed, or stale timestamps. Calculate HMAC-SHA256 over timestamp.raw_body and compare signatures using a constant-time function.
use Illuminate\Http\Request;
function receive(Request $request, string $secret) {
$timestamp = $request->header('X-Jawib-Timestamp', '');
$signature = $request->header('X-Jawib-Signature', '');
abort_unless(ctype_digit($timestamp), 401);
abort_if(abs(time() - (int) $timestamp) > 300, 401);
$expected = 'v1='.hash_hmac('sha256',
$timestamp.'.'.$request->getContent(), $secret);
abort_unless(hash_equals($expected, $signature), 401);
// Deduplicate the event ID and enqueue processing.
return response()->json(['received' => true]);
}
Event types
| Event | Description |
|---|---|
connection.updated | Connection state or relinking status changed. |
message.received | Captured inbound private message. |
message.outbound | Outbound private-message synchronization. |
message.sent, message.delivered, message.read, message.failed | Observed message-status update. |
group.message.content, group.message.outbound | Captured inbound or outbound group message. |
group.message.receipt | Observed delivery, read, or playback update for a group participant. |
conversation.updated | Conversation reply mode changed. |
Delivery and retries
Return a 2xx response promptly, then process events asynchronously. Failed deliveries may be retried, so events may arrive more than once or out of order. Retry backoff is 60 seconds, 5 minutes, 30 minutes, 2 hours, and 6 hours. Delivery records are retained for up to 7 days, subject to earlier content expiration. Repeated failures may disable an endpoint.
List webhook endpoints
curl --request GET "https://playjawib.com/api/v2/webhooks" \
--header "Authorization: Bearer $JAWIB_API_KEY" \
--header 'Accept: application/json'use Illuminate\Support\Facades\Http;
$response = Http::acceptJson()
->withToken(env('JAWIB_API_KEY'))
->send('GET', 'https://playjawib.com/api/v2/webhooks');
$data = $response->throw()->json();// Run in your server, e.g. Node.js. Never expose the token in browser code.
const response = await fetch('https://playjawib.com/api/v2/webhooks', {
method: 'GET',
headers: {
Authorization: `Bearer ${process.env.JAWIB_API_KEY}`,
Accept: 'application/json'
}
});
const data = await response.json();
if (!response.ok) throw new Error(data.message ?? 'Request failed');{
"data": []
}Illustrative values. Use the actual identifiers and credentials returned by your request.
Create a webhook endpoint
curl --request POST "https://playjawib.com/api/v2/webhooks" \
--header "Authorization: Bearer $JAWIB_API_KEY" \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
"name": "Application events",
"url": "https://example.com/webhooks/jawib",
"events": [
"message.received",
"message.read",
"group.message.receipt"
]
}'use Illuminate\Support\Facades\Http;
$response = Http::acceptJson()
->withToken(env('JAWIB_API_KEY'))
->send('POST', 'https://playjawib.com/api/v2/webhooks', [
'json' => json_decode(<<<'JSON'
{
"name": "Application events",
"url": "https://example.com/webhooks/jawib",
"events": [
"message.received",
"message.read",
"group.message.receipt"
]
}
JSON, true),
]);
$data = $response->throw()->json();// Run in your server, e.g. Node.js. Never expose the token in browser code.
const response = await fetch('https://playjawib.com/api/v2/webhooks', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.JAWIB_API_KEY}`,
Accept: 'application/json',
'Content-Type': 'application/json'
},
body: JSON.stringify({
"name": "Application events",
"url": "https://example.com/webhooks/jawib",
"events": [
"message.received",
"message.read",
"group.message.receipt"
]
})
});
const data = await response.json();
if (!response.ok) throw new Error(data.message ?? 'Request failed');Request body fields
| Field | Type | Description |
|---|---|---|
name | string | — |
urlrequired | string | Public HTTPS address; private networks are rejected. |
eventsrequired | array | — |
{
"data": {
"id": "12",
"secret": "whsec_REDACTED_EXAMPLE",
"url": "https://example.com/webhooks/jawib",
"events": [
"message.received",
"message.read",
"group.message.receipt"
]
}
}Illustrative values. Use the actual identifiers and credentials returned by your request.
Disable a webhook endpoint
Replace {endpoint} with the actual IDs returned by the API.
curl --request DELETE "https://playjawib.com/api/v2/webhooks/{endpoint}" \
--header "Authorization: Bearer $JAWIB_API_KEY" \
--header 'Accept: application/json'use Illuminate\Support\Facades\Http;
$response = Http::acceptJson()
->withToken(env('JAWIB_API_KEY'))
->send('DELETE', 'https://playjawib.com/api/v2/webhooks/{endpoint}');
$data = $response->throw()->json();// Run in your server, e.g. Node.js. Never expose the token in browser code.
const response = await fetch('https://playjawib.com/api/v2/webhooks/{endpoint}', {
method: 'DELETE',
headers: {
Authorization: `Bearer ${process.env.JAWIB_API_KEY}`,
Accept: 'application/json'
}
});
const data = await response.json();
if (!response.ok) throw new Error(data.message ?? 'Request failed');{
"disabled": true
}Illustrative values. Use the actual identifiers and credentials returned by your request.