웹훅 엔드포인트 API - WhereParcel

웹훅을 수신할 엔드포인트 URL 사전 등록 및 관리. 엔드포인트 테스트, 시크릿 키 갱신, 배송 상태 모니터링.

POST /v2/webhook-endpoints

웹훅 엔드포인트 생성

개요

웹훅을 받을 URL을 사전 등록합니다. 등록한 엔드포인트는 웹훅 등록 시 webhookEndpointId로 참조할 수 있습니다. 무료 API로 사용량이 차감되지 않습니다.

요청 예제

curl -X POST https://api.whereparcel.com/v2/webhook-endpoints \
  -H "Authorization: Bearer wp_test_public_demo_key_do_not_use_in_production:sk_test_public_demo_secret_do_not_use_in_production" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Webhook",
    "url": "https://myapp.com/webhooks/whereparcel",
    "description": "프로덕션 환경 웹훅 수신 URL"
  }'
const response = await fetch('https://api.whereparcel.com/v2/webhook-endpoints', {
  method: 'POST',
  headers: {
    "Authorization": "Bearer wp_test_public_demo_key_do_not_use_in_production:sk_test_public_demo_secret_do_not_use_in_production",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
      "name": "Production Webhook",
      "url": "https://myapp.com/webhooks/whereparcel",
      "description": "프로덕션 환경 웹훅 수신 URL"
    })
});

const data = await response.json();
console.log(data);
<?php

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://api.whereparcel.com/v2/webhook-endpoints');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');

$headers = [
  'Authorization: Bearer wp_test_public_demo_key_do_not_use_in_production:sk_test_public_demo_secret_do_not_use_in_production',
  'Content-Type: application/json'
];
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$data = [
  'name' => "Production Webhook",
  'url' => "https://myapp.com/webhooks/whereparcel",
  'description' => "프로덕션 환경 웹훅 수신 URL"
];
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
print_r($result);
import requests
import json

url = 'https://api.whereparcel.com/v2/webhook-endpoints'

headers = {
    'Authorization': 'Bearer wp_test_public_demo_key_do_not_use_in_production:sk_test_public_demo_secret_do_not_use_in_production',
    'Content-Type': 'application/json'
}

data = {
    'name': "Production Webhook",
    'url': "https://myapp.com/webhooks/whereparcel",
    'description': "프로덕션 환경 웹훅 수신 URL"
}

response = requests.post(url, headers=headers, json=data)

result = response.json()
print(result)
package main

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

func main() {
	url := "https://api.whereparcel.com/v2/webhook-endpoints"

	payload := []byte(`{"name":"Production Webhook","url":"https://myapp.com/webhooks/whereparcel","description":"프로덕션 환경 웹훅 수신 URL"}`)
	req, _ := http.NewRequest("POST", url, bytes.NewBuffer(payload))

	req.Header.Add("Authorization", "Bearer wp_test_public_demo_key_do_not_use_in_production:sk_test_public_demo_secret_do_not_use_in_production")
	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))
}
💡 참고: 테스트 API 키를 대시보드에서 발급받은 실제 API 키로 교체하세요.

요청 본문

Name Type Required Description
name string Required
url string Required
secret string Optional
description string Optional

응답

성공 응답 (201)

201 Created

엔드포인트 생성 성공

Response Body

{
  "success": true,
  "data": {
    "endpointId": "endpoint_abc123",
    "name": "Production Webhook",
    "url": "https://myapp.com/webhooks/whereparcel",
    "secret": "whsec_aBcDeFgHiJkLmNoPqRsTuVwXyZ123456",
    "description": "프로덕션 환경 웹훅 수신 URL",
    "isActive": true,
    "createdAt": "2026-02-05T10:00:00.000Z"
  }
}

오류 응답 (400)

400 Bad Request

잘못된 요청 (URL 형식 오류 등)

Response Body

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "The request parameters are invalid"
  }
}

오류 응답 (401)

401 Unauthorized

인증 실패

Response Body

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}
GET /v2/webhook-endpoints

웹훅 엔드포인트 목록 조회

개요

등록된 모든 웹훅 엔드포인트를 조회합니다. 무료 API로 사용량이 차감되지 않습니다.

요청 예제

curl -X GET https://api.whereparcel.com/v2/webhook-endpoints \
  -H "Authorization: Bearer wp_test_public_demo_key_do_not_use_in_production:sk_test_public_demo_secret_do_not_use_in_production" \
  -H "Content-Type: application/json"
const response = await fetch('https://api.whereparcel.com/v2/webhook-endpoints', {
  method: 'GET',
  headers: {
    "Authorization": "Bearer wp_test_public_demo_key_do_not_use_in_production:sk_test_public_demo_secret_do_not_use_in_production",
    "Content-Type": "application/json"
  }
});

const data = await response.json();
console.log(data);
<?php

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://api.whereparcel.com/v2/webhook-endpoints');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');

$headers = [
  'Authorization: Bearer wp_test_public_demo_key_do_not_use_in_production:sk_test_public_demo_secret_do_not_use_in_production',
  'Content-Type: application/json'
];
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
print_r($result);
import requests
import json

url = 'https://api.whereparcel.com/v2/webhook-endpoints'

headers = {
    'Authorization': 'Bearer wp_test_public_demo_key_do_not_use_in_production:sk_test_public_demo_secret_do_not_use_in_production',
    'Content-Type': 'application/json'
}

response = requests.get(url, headers=headers)

result = response.json()
print(result)
package main

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

func main() {
	url := "https://api.whereparcel.com/v2/webhook-endpoints"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer wp_test_public_demo_key_do_not_use_in_production:sk_test_public_demo_secret_do_not_use_in_production")
	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))
}
💡 참고: 테스트 API 키를 대시보드에서 발급받은 실제 API 키로 교체하세요.

응답

성공 응답 (200)

200 OK

엔드포인트 목록 조회 성공

Response Body

{
  "success": true,
  "data": [
    {
      "endpointId": "endpoint_abc123",
      "name": "Production Webhook",
      "url": "https://myapp.com/webhooks/whereparcel",
      "description": "프로덕션 환경 웹훅 수신 URL",
      "isActive": true,
      "createdAt": "2026-02-05T10:00:00.000Z",
      "updatedAt": "2026-02-05T10:00:00.000Z"
    },
    {
      "endpointId": "endpoint_def456",
      "name": "Staging Webhook",
      "url": "https://staging.myapp.com/webhooks/whereparcel",
      "description": "스테이징 환경 웹훅 수신 URL",
      "isActive": false,
      "createdAt": "2026-02-04T15:30:00.000Z",
      "updatedAt": "2026-02-04T16:00:00.000Z"
    }
  ]
}

오류 응답 (401)

401 Unauthorized

인증 실패

Response Body

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}
PUT /v2/webhook-endpoints/{endpointId}

웹훅 엔드포인트 수정

개요

웹훅 엔드포인트의 정보를 수정합니다. URL, 이름, 설명, 활성화 상태 등을 변경할 수 있습니다. 무료 API로 사용량이 차감되지 않습니다.

요청 예제

curl -X PUT https://api.whereparcel.com/v2/webhook-endpoints/{endpointId} \
  -H "Authorization: Bearer wp_test_public_demo_key_do_not_use_in_production:sk_test_public_demo_secret_do_not_use_in_production" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Webhook Name",
    "url": "https://myapp.com/webhooks/new-url",
    "enabled": true
  }'
const response = await fetch('https://api.whereparcel.com/v2/webhook-endpoints/{endpointId}', {
  method: 'PUT',
  headers: {
    "Authorization": "Bearer wp_test_public_demo_key_do_not_use_in_production:sk_test_public_demo_secret_do_not_use_in_production",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
      "name": "Updated Webhook Name",
      "url": "https://myapp.com/webhooks/new-url",
      "enabled": true
    })
});

const data = await response.json();
console.log(data);
<?php

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://api.whereparcel.com/v2/webhook-endpoints/{endpointId}');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');

$headers = [
  'Authorization: Bearer wp_test_public_demo_key_do_not_use_in_production:sk_test_public_demo_secret_do_not_use_in_production',
  'Content-Type: application/json'
];
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$data = [
  'name' => "Updated Webhook Name",
  'url' => "https://myapp.com/webhooks/new-url",
  'enabled' => true
];
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
print_r($result);
import requests
import json

url = 'https://api.whereparcel.com/v2/webhook-endpoints/{endpointId}'

headers = {
    'Authorization': 'Bearer wp_test_public_demo_key_do_not_use_in_production:sk_test_public_demo_secret_do_not_use_in_production',
    'Content-Type': 'application/json'
}

data = {
    'name': "Updated Webhook Name",
    'url': "https://myapp.com/webhooks/new-url",
    'enabled': True
}

response = requests.put(url, headers=headers, json=data)

result = response.json()
print(result)
package main

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

func main() {
	url := "https://api.whereparcel.com/v2/webhook-endpoints/{endpointId}"

	payload := []byte(`{"name":"Updated Webhook Name","url":"https://myapp.com/webhooks/new-url","enabled":true}`)
	req, _ := http.NewRequest("PUT", url, bytes.NewBuffer(payload))

	req.Header.Add("Authorization", "Bearer wp_test_public_demo_key_do_not_use_in_production:sk_test_public_demo_secret_do_not_use_in_production")
	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))
}
💡 참고: 테스트 API 키를 대시보드에서 발급받은 실제 API 키로 교체하세요.

경로 매개변수

Name Type Required Description
endpointId string Required
<p>수정할 엔드포인트 ID</p>
Example: endpoint_abc123

요청 본문

Name Type Required Description
name string Optional
url string Optional
description string Optional
isActive boolean Optional

응답

성공 응답 (200)

200 OK

엔드포인트 수정 성공

Response Body

{
  "success": true,
  "data": {
    "endpointId": "endpoint_abc123",
    "name": "Updated Webhook Name",
    "url": "https://myapp.com/webhooks/new-url",
    "description": "Updated description",
    "isActive": true,
    "updatedAt": "2026-02-05T11:00:00.000Z"
  }
}

오류 응답 (401)

401 Unauthorized

인증 실패

Response Body

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

오류 응답 (404)

404 Not Found

endpointId를 찾을 수 없음

Response Body

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "The requested resource was not found"
  }
}
DELETE /v2/webhook-endpoints/{endpointId}

웹훅 엔드포인트 삭제

개요

웹훅 엔드포인트를 삭제합니다. 이 엔드포인트를 사용 중인 웹훅이 있으면 삭제할 수 없습니다. 무료 API로 사용량이 차감되지 않습니다.

요청 예제

curl -X DELETE https://api.whereparcel.com/v2/webhook-endpoints/{endpointId} \
  -H "Authorization: Bearer wp_test_public_demo_key_do_not_use_in_production:sk_test_public_demo_secret_do_not_use_in_production" \
  -H "Content-Type: application/json"
const response = await fetch('https://api.whereparcel.com/v2/webhook-endpoints/{endpointId}', {
  method: 'DELETE',
  headers: {
    "Authorization": "Bearer wp_test_public_demo_key_do_not_use_in_production:sk_test_public_demo_secret_do_not_use_in_production",
    "Content-Type": "application/json"
  }
});

const data = await response.json();
console.log(data);
<?php

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://api.whereparcel.com/v2/webhook-endpoints/{endpointId}');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');

$headers = [
  'Authorization: Bearer wp_test_public_demo_key_do_not_use_in_production:sk_test_public_demo_secret_do_not_use_in_production',
  'Content-Type: application/json'
];
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
print_r($result);
import requests
import json

url = 'https://api.whereparcel.com/v2/webhook-endpoints/{endpointId}'

headers = {
    'Authorization': 'Bearer wp_test_public_demo_key_do_not_use_in_production:sk_test_public_demo_secret_do_not_use_in_production',
    'Content-Type': 'application/json'
}

response = requests.delete(url, headers=headers)

result = response.json()
print(result)
package main

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

func main() {
	url := "https://api.whereparcel.com/v2/webhook-endpoints/{endpointId}"

	req, _ := http.NewRequest("DELETE", url, nil)

	req.Header.Add("Authorization", "Bearer wp_test_public_demo_key_do_not_use_in_production:sk_test_public_demo_secret_do_not_use_in_production")
	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))
}
💡 참고: 테스트 API 키를 대시보드에서 발급받은 실제 API 키로 교체하세요.

경로 매개변수

Name Type Required Description
endpointId string Required
<p>삭제할 엔드포인트 ID</p>
Example: endpoint_abc123

응답

성공 응답 (200)

200 OK

엔드포인트 삭제 성공

Response Body

{
  "success": true,
  "message": "Webhook endpoint deleted successfully"
}

오류 응답 (401)

401 Unauthorized

인증 실패

Response Body

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

오류 응답 (404)

404 Not Found

endpointId를 찾을 수 없음

Response Body

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "The requested resource was not found"
  }
}

오류 응답 (409)

409 409

사용 중인 엔드포인트는 삭제할 수 없음

Response Body

{
  "success": false,
  "error": {
    "code": "ERROR",
    "message": "An error occurred"
  }
}