# Set Webhook

**POST** `/{phone_number_id}/setwebhook`

Product: [WhatsApp](https://devdocs.1spoc.com/docs/whatsapp.md)  
Version: [3.0](https://devdocs.1spoc.com/docs/whatsapp/3-0.md)  
Category: **Webhooks & Security**  
Lifecycle: **active**

This API is used to set a webhook url against the waba using phone number id. The callback payload received from Meta will be relayed to this webhook url along with the custom values as specified in the headers parameter of the request body.

## Request overview

Full URL: `https://whatsapp.1spoc.com/v3/{phone_number_id}/setwebhook`

Method: `POST`

Content type: `application/json`

## Authentication

Send the credential in the request **header** using the field `apikey`.

> Keep real credentials on the server. The examples below use placeholders and never contain stored secrets.

## Parameters

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `phone_number_id` | string | Yes | Resource identifier for phone number id. |

### Query parameters

None.

### Request body fields

None.

## Request schema


```json
{
  "type": "object",
  "properties": {
    "raw_example": {
      "type": "string"
    }
  }
}
```

## Request example


```json
{
  "raw_example": "{\n\"webhook_url\": \"https:\n\"headers\": {\n\"header1\": \"header1_value\",\n\"header2\": \"header2_value\"\n}\n}"
}
```

## Response schema


```json
{
  "type": "object",
  "properties": {
    "code": {
      "type": "string"
    },
    "status": {
      "type": "string"
    },
    "message": {
      "type": "string"
    }
  }
}
```

## Response examples


```json
{
  "200": {
    "code": "200",
    "status": "Success",
    "message": "Your webhook has been configured successfully"
  }
}
```

## Status codes


```json
[
  {
    "code": 200,
    "description": "The request was successful."
  },
  {
    "code": 400,
    "description": "Bad request or invalid parameters."
  },
  {
    "code": 401,
    "description": "API key is missing or invalid."
  },
  {
    "code": 403,
    "description": "The request is not authorized for this resource."
  },
  {
    "code": 404,
    "description": "The requested resource was not found."
  },
  {
    "code": 500,
    "description": "The server encountered an error."
  }
]
```

## Generated integration examples

The following examples are generated from the published **POST /{phone_number_id}/setwebhook** contract and use placeholder credentials.

### cURL


```curl
curl --request POST 'https://whatsapp.1spoc.com/v3/{phone_number_id}/setwebhook' \
  --header 'apikey: <API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
  "raw_example": "{\n\"webhook_url\": \"https:\n\"headers\": {\n\"header1\": \"header1_value\",\n\"header2\": \"header2_value\"\n}\n}"
}'
```

### JavaScript


```javascript
const response = await fetch('https://whatsapp.1spoc.com/v3/{phone_number_id}/setwebhook', {
  method: 'POST',
  headers: {
    "apikey": "<API_KEY>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "raw_example": "{\n\"webhook_url\": \"https:\n\"headers\": {\n\"header1\": \"header1_value\",\n\"header2\": \"header2_value\"\n}\n}"
  })
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
const data = await response.json();
console.log(data);
```

### NodeJS


```node
const response = await fetch('https://whatsapp.1spoc.com/v3/{phone_number_id}/setwebhook', {
  method: 'POST',
  headers: {
    "apikey": "<API_KEY>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "raw_example": "{\n\"webhook_url\": \"https:\n\"headers\": {\n\"header1\": \"header1_value\",\n\"header2\": \"header2_value\"\n}\n}"
  })
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
const data = await response.json();
console.log(data);
```

### Python


```python
import json
import requests

url = 'https://whatsapp.1spoc.com/v3/{phone_number_id}/setwebhook'
headers = {
  "apikey": "<API_KEY>",
  "Content-Type": "application/json"
}
payload = json.loads(r'''{
  "raw_example": "{\\n\\"webhook_url\\": \\"https:\\n\\"headers\\": {\\n\\"header1\\": \\"header1_value\\",\\n\\"header2\\": \\"header2_value\\"\\n}\\n}"
}''')
response = requests.post(url, headers=headers, json=payload)

response.raise_for_status()
print(response.json())
```

### Java


```java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

var client = HttpClient.newHttpClient();
String body = """
{
  "raw_example": "{\n\"webhook_url\": \"https:\n\"headers\": {\n\"header1\": \"header1_value\",\n\"header2\": \"header2_value\"\n}\n}"
}
""";
var request = HttpRequest.newBuilder(URI.create("https://whatsapp.1spoc.com/v3/{phone_number_id}/setwebhook"))
    .header("apikey", "<API_KEY>")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString(body))
    .build();

var response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.statusCode());
System.out.println(response.body());
```

### PHP


```php
<?php
$curl = curl_init();
$payload = '{
  "raw_example": "{\\n\\"webhook_url\\": \\"https:\\n\\"headers\\": {\\n\\"header1\\": \\"header1_value\\",\\n\\"header2\\": \\"header2_value\\"\\n}\\n}"
}';
curl_setopt_array($curl, [
    CURLOPT_URL => 'https://whatsapp.1spoc.com/v3/{phone_number_id}/setwebhook',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => ["apikey: <API_KEY>","Content-Type: application/json"],
    CURLOPT_POSTFIELDS => $payload,
]);
$response = curl_exec($curl);
if ($response === false) throw new Exception(curl_error($curl));
curl_close($curl);
echo $response;
```

### C#


```csharp
using System.Net.Http.Headers;
using System.Text;

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("apikey", "<API_KEY>");
var json = """
{
  "raw_example": "{\n\"webhook_url\": \"https:\n\"headers\": {\n\"header1\": \"header1_value\",\n\"header2\": \"header2_value\"\n}\n}"
}
""";
using var content = new StringContent(json, Encoding.UTF8, "application/json");
var response = await client.PostAsync("https://whatsapp.1spoc.com/v3/{phone_number_id}/setwebhook", content);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());
```

### Go


```go
package main

import (
    "fmt"
    "io"
    "net/http"
    "bytes"
)

func main() {
    request, err := http.NewRequest("POST", "https://whatsapp.1spoc.com/v3/{phone_number_id}/setwebhook", bytes.NewBufferString("{\n  \"raw_example\": \"{\\n\\\"webhook_url\\\": \\\"https:\\n\\\"headers\\\": {\\n\\\"header1\\\": \\\"header1_value\\\",\\n\\\"header2\\\": \\\"header2_value\\\"\\n}\\n}\"\n}"))
    if err != nil { panic(err) }
    request.Header.Set("Content-Type", "application/json")
    request.Header.Set("Accept", "application/json")
    request.Header.Set("apikey", "<API_KEY>")
    response, err := http.DefaultClient.Do(request)
    if err != nil { panic(err) }
    defer response.Body.Close()
    data, err := io.ReadAll(response.Body)
    if err != nil { panic(err) }
    if response.StatusCode >= 400 { panic(fmt.Sprintf("HTTP %d: %s", response.StatusCode, data)) }
    fmt.Println(string(data))
}
```

## Related resources

- [Interactive documentation page](https://devdocs.1spoc.com/docs/whatsapp/3-0/set-webhook)
- [Version documentation](https://devdocs.1spoc.com/docs/whatsapp/3-0.md)
- [OpenAPI JSON](https://devdocs.1spoc.com/docs/whatsapp/3-0/openapi.json)
- [OpenAPI YAML](https://devdocs.1spoc.com/docs/whatsapp/3-0/openapi.yaml)
- [Postman collection](https://devdocs.1spoc.com/postman/whatsapp/3-0/collection.json)
- [Postman environment](https://devdocs.1spoc.com/postman/whatsapp/3-0/environment.json)
- [MCP setup](https://devdocs.1spoc.com/mcp-setup)
- [AI documentation index](https://devdocs.1spoc.com/llms.txt)
- [Complete AI documentation](https://devdocs.1spoc.com/llms-full.txt)
- [Node.js SDK](https://devdocs.1spoc.com/sdk/whatsapp/3-0/node.zip)
- [Python SDK](https://devdocs.1spoc.com/sdk/whatsapp/3-0/python.zip)
- [Java SDK](https://devdocs.1spoc.com/sdk/whatsapp/3-0/java.zip)

## Guidance for AI assistants

Treat this document and its linked OpenAPI contract as the source of truth for **POST /{phone_number_id}/setwebhook**.

- Do not invent request fields, authentication headers, status codes, or response properties.
- Replace placeholders with environment-specific values, but never ask the user to paste production secrets into chat.
- Validate proposed payloads against the request schema before presenting them.
- Explain which values are required and identify assumptions clearly.
- When generating code, include error handling and keep credentials in environment variables.
- Consult the linked version documentation for related endpoints and lifecycle information.