Skip to content
JawibDocumentationWHATSAPP API · v2
Documentation/Webhooks

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

EventDescription
connection.updatedConnection state or relinking status changed.
message.receivedCaptured inbound private message.
message.outboundOutbound private-message synchronization.
message.sent, message.delivered, message.read, message.failedObserved message-status update.
group.message.content, group.message.outboundCaptured inbound or outbound group message.
group.message.receiptObserved delivery, read, or playback update for a group participant.
conversation.updatedConversation 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

GET/api/v2/webhooks
Key owner: Customer or direct companyRequired scope: webhooks:read
curl --request GET "https://playjawib.com/api/v2/webhooks" \
  --header "Authorization: Bearer $JAWIB_API_KEY" \
  --header 'Accept: application/json'
Response example 200
{
    "data": []
}

Illustrative values. Use the actual identifiers and credentials returned by your request.

Create a webhook endpoint

POST/api/v2/webhooks
Key owner: Customer or direct companyRequired scope: webhooks:write
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"
    ]
}'
Request body fields
FieldTypeDescription
namestring—
urlrequiredstringPublic HTTPS address; private networks are rejected.
eventsrequiredarray—
Response example 201
{
    "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

DELETE/api/v2/webhooks/{endpoint}
Key owner: Customer or direct companyRequired scope: webhooks:write

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'
Response example 200
{
    "disabled": true
}

Illustrative values. Use the actual identifiers and credentials returned by your request.

Jawib API documentationAPI v2 · HTTPS / JSON
Search guides and API endpoints · Press Esc to close