Skip to main content

자격 부여 웹훅 이벤트

고객의 자격 부여가 상태를 변경할 때마다 예를 들어 라이선스 키가 생성되거나, Discord 역할이 할당되거나, 다운로드 링크가 제공되거나, 액세스가 취소될 때 트리거됩니다. 이러한 이벤트에 구독하여 각 고객이 액세스할 수 있는 내용을 지속적으로 동기화하세요. 모든 네 개의 이벤트는 아래 스키마에 문서화된 동일한 EntitlementGrantResponse 페이로드를 공유합니다.

이벤트 트리거

entitlement_grant.created

방금 부여 행이 삽입되었습니다. 이 시점부터 부여는 안정적인 id를 항상 가지고 있으며, 상태가 변경되더라도 마찬가지입니다. 이 이벤트를 사용하여 이행이 진행 중임을 기록하세요. auto-fulfilled license keys의 경우 행이 status: "Delivered"delivered_at가 채워진 상태로 직접 삽입되므로, 단일 created 이벤트 후에는 grant가 나중에 revoke되지 않는 한 추가 상태 변경이 발생하지 않습니다. manually-fulfilled license keys(fulfillment_mode: manual가 있는 entitlement)의 경우 행이 status: "Pending" 상태로 도착하고 license_key 객체는 없습니다. 아직 key가 발급되지 않은 것입니다. 이 이벤트는 key가 fulfillment를 기다리고 있다는 신호입니다. POST /grants/{grant_id}/license-key를 통해 key를 제공하면 entitlement_grant.delivered가 발생합니다. Manual Fulfillment를 참조하세요. 그 외 모든 integration의 경우 행이 status: "Pending" 상태로 도착합니다. delivery가 완료되면 delivered 또는 failed 이벤트가 이어집니다:
  • OAuth-based integrations(Discord, GitHub, Notion)에는 customer가 방문하여 동의를 완료해야 하는 oauth_url가 포함됩니다. customer가 authorize할 때까지 grant는 Pending 상태로 유지됩니다.
  • Platform-direct integrations(Telegram, Framer, Digital Files)은 platform call이 실행되는 동안에만 잠시 Pending 상태에 머문 후 Delivered로 전환됩니다.
부여는 pending에서 delivered로 전환되었습니다. 이제 고객은 자격 부여된 액세스를 받았습니다. 이 이벤트를 사용하여 작업 공간을 제공하거나, 맞춤 환영 이메일을 보내거나, “이행 완료” 플래그를 표시하는 등의 종속 기능을 잠금 해제하세요. grant가 Pending에서 Delivered로 전환되었습니다. 이제 customer가 entitlement에 설명된 액세스 권한을 보유합니다. 이 이벤트를 사용하여 자체 시스템에서 종속 기능을 활성화하세요. 예를 들어 workspace를 provision하거나, 맞춤형 welcome email을 보내거나, “fulfilled” flag를 표시할 수 있습니다. payload의 delivered_at field에는 delivery가 완료된 시점이 기록됩니다. 생성 시 Delivered 상태였던 grant의 경우 createddelivered 이벤트를 연속으로 수신합니다. 전달이 시도되었으나 다시 시도할 수 없는 오류로 실패했습니다. error_codeerror_message 필드는 실패 원인을 설명합니다. 일반적인 원인으로는 철회된 OAuth 토큰, 허가된 플랫폼 권한 거부 또는 삭제된 Discord 길드와 같은 대상 누락이 포함됩니다.
entitlement_grant.failed를 실행 가능한 문제로 처리하십시오. 고객은 지불했으나 액세스를 받지 못했습니다. 지원 팀에 실패를 알리거나 근본적인 문제가 해결된 후 재부여를 트리거하십시오.

entitlement_grant.revoked

플랫폼 수준에서 액세스가 철회되었습니다: Discord 역할 제거, GitHub 협력자 제거, 라이선스 키 비활성화, 파일 다운로드 URL 더 이상 발행되지 않음. revocation_reason 필드는 트리거를 기록합니다.

페이로드 변형

data 필드는 항상 EntitlementGrantResponse 객체입니다. 두 가지 통합 유형은 추가 중첩 객체를 첨부합니다: data field는 항상 EntitlementGrantResponse object입니다. payload에는 integration_type field가 포함되어 있어(예: license_key, digital_files, discord) grant type을 직접 식별할 수 있습니다. 세 가지 integration type에는 추가 중첩 object도 포함됩니다:
  • **license_key**는 integration_typelicense_key이고 key가 발급된 경우 포함됩니다. 생성된 key, 만료일 및 activation usage가 들어 있습니다. 아직 Pending 상태인 manually-fulfilled grant의 경우 grant를 fulfill할 때까지 이 object는 null입니다.
  • **digital_product_delivery**는 integration_typedigital_files인 경우 포함됩니다. presigned download URL, 선택적 instructions 및 선택적 external_url가 들어 있습니다.
  • **feature**는 integration_typefeature_flag인 경우 포함됩니다. grant가 부여하는 capability의 feature_typefeature_id가 들어 있습니다.
그 외 모든 integration type(Discord, GitHub, Telegram, Figma, Framer, Notion)에서는 이러한 중첩 field가 null입니다. 관련 configuration은 grant가 아니라 entitlement 자체에 기록됩니다.

샘플 페이로드

라이선스 키 전송 완료 (entitlement_grant.delivered)

customer가 fulfillment_mode: manual를 사용하는 License Key entitlement가 포함된 product를 구매할 때 발생합니다. grant는 아직 license_key object가 없는 Pending 상태이며, merchant가 key를 제공해야 합니다.

구독 취소 시 부여 철회됨 (entitlement_grant.revoked)

전달 실패 (entitlement_grant.failed)


  • 종속 기능 잠금 해제를 위해 entitlement_grant.delivered를 기다리세요. payment.succeeded 이벤트는 금액이 정산되었다는 것을 알려줄 뿐이며, 고객이 GitHub 리포지토리나 Discord 역할을 가졌다는 것을 알려주지 않습니다. delivered 이벤트가 이행을 위한 신뢰할 수 있는 출처입니다.
  • revocation_reason를 유지 흐름에 매핑하세요. subscription_on_hold 철회는 일반적으로 고객의 카드가 실패했고, 다음 갱신이 액세스를 재부여할 것이라는 것을 의미합니다. manual 또는 subscription_cancelled 철회는 의도적입니다. 고객 메시지에서 이들을 다르게 처리하십시오.
  • 그랜트 id를 불변성 키로 사용하십시오. 단일 그랜트는 최대 하나의 created 이벤트와 최대 하나의 터미널 이벤트 (delivered 또는 failed), 최대 하나의 revoked 이벤트를 발생시킵니다. 웹훅 시스템의 재전달은 이벤트를 반복할 수 있습니다. 그랜트 id 플러스 type에서 중복을 제거하십시오.
  • 통합 유형을 인식하기 위해 license_keydigital_product_delivery를 검사하세요. 그랜트 페이로드 자체에는 통합 유형이 포함되어 있지 않지만, 라이선스 키 및 디지털 파일 자격에서는 이 중 하나의 중첩 객체가 정확히 채워집니다.
  • OAuth 기반 부여의 경우 oauth_url를 고객에게 노출하세요. Discord, GitHub, Notion 가입자 흐름에 대한 entitlement_grant.created 이벤트에는 oauth_urloauth_expires_at가 포함됩니다. 이메일로 보내거나 앱에 표시하여 전달을 차단 해제하세요.

통합 팁

  • 종속 기능을 활성화하기 전에 entitlement_grant.delivered를 기다리세요. payment.succeeded 이벤트는 결제가 완료되었음을 의미할 뿐, customer가 아직 GitHub repo 또는 Discord role을 보유하고 있다는 뜻은 아닙니다. fulfillment의 source of truth는 delivered 이벤트입니다.
  • revocation_reason를 retention flow에 매핑하세요. subscription_on_hold revoke는 일반적으로 customer의 card 결제가 실패했으며 다음 renewal 시 액세스가 다시 부여된다는 의미입니다. manual 또는 subscription_cancelled revoke는 의도적인 취소입니다. customer messaging에서 두 경우를 다르게 처리하세요.
  • grant의 id를 idempotency key로 사용하세요. 하나의 grant는 최대 하나의 created 이벤트와 최대 하나의 terminal event(delivered 또는 failed), 그리고 최대 하나의 revoked 이벤트를 발생시킵니다. webhook system의 재전달로 이벤트가 반복될 수 있으므로, grant의 idtype를 기준으로 중복 제거하세요.
  • integration_type를 읽어 grant type을 식별하세요. payload에는 integration_type가 직접 포함됩니다(예: license_key, digital_files, discord). license_keydigital_product_delivery 중첩 object는 해당 grant가 delivered되면 채워집니다. manually-fulfilled license-key grant는 fulfill할 때까지 integration_type: "license_key"nulllicense_key와 함께 Pending 상태로 유지됩니다.
  • OAuth-based grant의 경우 oauth_url를 customer에게 표시하세요. Discord, GitHub 또는 Notion subscriber flow의 entitlement_grant.created 이벤트에는 oauth_urloauth_expires_at가 포함됩니다. 이를 customer에게 email로 보내거나 app에 표시하여 delivery를 진행할 수 있도록 하세요.

Detailed view of a single entitlement grant: who it's for, its lifecycle state, and any integration-specific delivery payload.

brand_id
string
필수

Brand id this grant belongs to.

business_id
string
필수

Identifier of the business that owns the grant.

created_at
string<date-time>
필수

Timestamp when the grant was created.

customer_id
string
필수

Identifier of the customer the grant was issued to.

entitlement_id
string
필수

Identifier of the entitlement this grant was issued from.

id
string
필수

Unique identifier of the grant.

integration_type
enum<string>
필수

The integration type of the grant's entitlement (e.g. license_key).

사용 가능한 옵션:
discord,
telegram,
github,
figma,
framer,
notion,
digital_files,
license_key,
feature_flag
metadata
Metadata · object
필수

Arbitrary key-value metadata recorded on the grant.

status
enum<string>
필수

Lifecycle status of the grant.

사용 가능한 옵션:
Pending,
Delivered,
Failed,
Revoked
updated_at
string<date-time>
필수

Timestamp when the grant was last modified.

delivered_at
string<date-time> | null

Timestamp when the grant transitioned to delivered, when applicable.

digital_product_delivery
null | Digital Product Delivery · object

Digital-product-delivery payload, present when the entitlement integration is digital_files.

error_code
string | null

Machine-readable code reported when delivery failed, when applicable.

error_message
string | null

Human-readable message reported when delivery failed, when applicable.

feature
null | object

Typed feature payload, present only when the entitlement integration is feature_flag; null for every other integration type.

license_key
null | object

License-key delivery payload, present when the entitlement integration is license_key.

oauth_expires_at
string<date-time> | null

Timestamp when oauth_url stops being valid, when applicable.

oauth_url
string | null

Customer-facing OAuth URL for OAuth-style integrations. Populated during the customer-portal accept flow; null until the customer completes that step, and on grants for non-OAuth integrations.

payment_id
string | null

Identifier of the payment that triggered this grant, when applicable.

revocation_reason
string | null

Reason recorded when the grant was revoked, when applicable.

revoked_at
string<date-time> | null

Timestamp when the grant transitioned to revoked, when applicable.

subscription_id
string | null

Identifier of the subscription that triggered this grant, when applicable.

마지막 수정일 2026년 8월 21일