GET /webhooks/{id}

Mengambil satu endpoint beserta secret-nya. Endpoint ini satu-satunya cara mendapatkan kembali secret setelah pendaftaran, jadi perlakukan responsnya sebagai data rahasia dan jangan menuliskannya ke log.

#Endpoint

bash

GET https://se-hari.com/api/v1/webhooks/{id}

Butuh scope webhooks:read. Scope ditetapkan saat key dibuat dan tidak bisa ditambahkan belakangan — kalau key Anda kurang izin, buat key baru lalu cabut yang lama. Kekakuan ini disengaja: scope yang bisa dinaikkan diam-diam berarti key yang bocor hari ini bisa menjadi lebih berbahaya besok. Beri setiap integrasi key sendiri dengan scope sesempit mungkin, supaya mencabut satu integrasi tidak pernah berarti mematikan yang lain.

#Parameter path

Parameter	Tipe	Wajib	Keterangan
`id`	`string`	ya	min 1 karakter

#Contoh

bash

curl -X GET "https://se-hari.com/api/v1/webhooks/c0ffee00-1111-2222-3333-444455556666" \
  -H "Authorization: Bearer $SEHARI_API_KEY"

javascript

const res = await fetch('https://se-hari.com/api/v1/webhooks/c0ffee00-1111-2222-3333-444455556666', {
	method: 'GET',
	headers: {
			'Authorization': `Bearer ${process.env.SEHARI_API_KEY}`,
		}
});

if (!res.ok) {
	const { error } = await res.json();
	// error.code stabil dan bisa dicabang; error.message untuk manusia.
	throw new Error(`${error.code}: ${error.message}`);
}

const data = await res.json();

python

import os, requests

res = requests.get(
    "https://se-hari.com/api/v1/webhooks/c0ffee00-1111-2222-3333-444455556666",
    headers={"Authorization": f"Bearer {os.environ['SEHARI_API_KEY']}"},
    timeout=30,
)

if not res.ok:
    err = res.json()["error"]
    raise RuntimeError(f"{err['code']}: {err['message']}")

data = res.json()

#Field respons

Field	Tipe	Keterangan
`id`	`string`	—
`url`	`string`	—
`description`	`string` \| `null`	—
`event_types`	`array<string>`	—
`is_active`	`boolean`	—
`consecutive_failures`	`integer`	—
`disabled_at`	`string` \| `null`	—
`created_by`	`string`	—
`created_at`	`string`	—
`secret`	`string`	—

#Kalau gagal

Setiap kegagalan memakai amplop yang sama, dan code di dalamnya stabil — cabangkan logika Anda ke sana, jangan ke message yang teksnya bisa diperbaiki sewaktu-waktu.

json

{
  "error": {
    "code": "invalid_api_key",
    "message": "Penjelasan untuk manusia.",
    "docs_url": "https://se-hari.com/docs/error/invalid-api-key",
    "request_id": "req_a1b2c3d4e5f6",
    "details": {}
  }
}

Status	Kode	Artinya di endpoint ini
401	`invalid_api_key`	Key salah, sudah dicabut, atau kedaluwarsa.
403	`insufficient_scope`	Key valid, tapi tidak punya scope yang dibutuhkan endpoint ini.
404	`not_found`	Data tidak ada, atau ada tapi milik akun lain — keduanya dijawab sama.
429	`rate_limited`	Terlalu banyak request. Hormati header `Retry-After`.
500	`internal_error`	Kesalahan di sisi kami. Sertakan `request_id` saat melapor.
Simpan `request_id` dari setiap respons gagal. Itu satu-satunya cara kami menemukan kembali request Anda di log ketika Anda melapor, dan ia juga ada di header `X-Request-Id` pada respons yang berhasil.

#Jangan dipanggil dalam perulangan

Endpoint ini untuk memeriksa konfigurasi, bukan untuk dipantau. Isinya hanya berubah ketika Anda sendiri yang mengubahnya, jadi memanggilnya berkala tidak akan pernah memberi tahu apa pun yang baru.

Yang mungkin Anda cari sebenarnya adalah GET /webhooks/{id}/deliveries — di sana terlihat kiriman mana yang berhasil, mana yang gagal, dan berapa kode respons dari endpoint Anda. Itu diagnostik yang berguna; consecutive_failures pada endpoint ini hanya angka ringkasannya.

#Alur khas

Webhook membalik arah komunikasi: alih-alih Anda menanyakan status berulang kali, Se-Hari yang memanggil endpoint Anda begitu ada kabar. Ini satu-satunya cara yang masuk akal untuk mengetahui notulen selesai, karena pemrosesannya bisa memakan beberapa menit.

POST /webhooks dengan URL https publik Anda dan daftar event — simpan secret dari respons
Verifikasi header X-Sehari-Signature di setiap kiriman yang masuk
Jawab 2xx secepatnya; kerjakan proses beratnya setelah membalas
GET /webhooks/{id}/deliveries kalau ada yang tampak tidak sampai

secret hanya ditampilkan sekali, saat endpoint dibuat. Kalau hilang, pakai POST /webhooks/{id}/rotate-secret untuk mendapatkan yang baru — dan ingat bahwa kiriman yang sedang dalam antrean retry akan ditandatangani dengan secret baru itu.

#Yang sering keliru

Key disalin sebagian. API key Se-Hari panjangnya tetap: sh_live_ diikuti 43 karakter. Kalau panjangnya berbeda, yang salah adalah proses penyalinannya, bukan key-nya — dan pesan 401 tidak akan mengatakan itu.
Scope kurang, bukan key salah. 403 di sini berarti key-nya dikenali. Periksa scope-nya lewat GET /me, lalu buat key baru kalau memang kurang; scope tidak bisa ditambahkan ke key yang sudah jadi.
404 tidak selalu berarti data tidak ada. Data milik akun lain juga dijawab 404, bukan 403 — kami tidak mengonfirmasi keberadaan id milik orang lain. Kalau Anda yakin id-nya benar, periksa apakah key yang dipakai milik akun yang sama.
Hormati Retry-After. Mencoba lagi lebih cepat dari yang disebutkan hanya memperpanjang masa tunggu. Kalau Anda sering menyentuhnya, kemungkinan besar Anda sedang polling sesuatu yang seharusnya ditangani webhook.

#Selanjutnya

Autentikasi dan API key — cara membuat key dan memilih scope
Kode error — arti setiap kode dan cara memperbaikinya
Idempotency — kenapa retry aman kalau dilakukan dengan benar
Spesifikasi OpenAPI — kontrak mesin, cocok untuk men-generate klien